template:
  id: design-story-template-v1
  name: Design/Research Story Document
  version: 1.0
  description: Template for design, research, architecture, and documentation planning stories
  use_cases:
    - UX design and user research
    - Architecture planning and design
    - Documentation planning and strategy
    - Research and analysis work
    - Non-development planning tasks
  output:
    format: markdown
    filename: docs/stories/{{epic_num}}.{{story_num}}.{{story_title_short}}.md
    title: "Story {{epic_num}}.{{story_num}}: {{story_title_short}}"

workflow:
  mode: interactive
  elicitation: advanced-elicitation
  story_type: design

agent_config:
  primary_agents:
    - ux-design-expert
    - architect
    - analyst
  editable_sections:
    - Status
    - Story
    - Objective
    - Scope
    - CodeRabbit Integration
    - Tasks Breakdown
    - Testing & Validation
    - Acceptance Criteria
    - Deliverables
    - Dev Notes
    - Change Log

sections:
  - id: header
    title: Story Header
    type: metadata
    instruction: Define story metadata including ID, epic, wave, status, priority, owner, dates
    template: |
      # Story {{epic_num}}.{{story_num}}: {{story_title}}

      **Story ID:** STORY-{{epic_num}}.{{story_num}}
      **Epic:** Epic {{epic_num}} - {{epic_title}}
      **Wave:** Wave {{wave_num}} ({{wave_name}})
      **Status:** {{status_emoji}} {{status}}
      **Priority:** {{priority_emoji}} {{priority}}
      **Owner:** {{owner_agents}}
      **Created:** {{creation_date}}
      **Duration:** {{duration}}
      **Investment:** ${{investment}}
    elicit: true
    owner: po
    editors: [po, sm]

  - id: story
    title: Story
    type: template-text
    template: |
      **As a** {{role}},
      **I want** {{action}},
      **so that** {{benefit}}
    instruction: Define the user story using the standard format with role, action, and benefit
    elicit: true
    owner: po
    editors: [po]

  - id: objective
    title: Objective
    type: free-text
    instruction: |
      Provide a clear, concise statement of what this story aims to achieve.
      Focus on the "what" and "why" of the design/research work.
    example: |
      Define complete personas for all 13 AIOS agents with names, roles, archetypes,
      colors, and icons to establish the foundation for the agent identity system.
    elicit: true
    owner: po
    editors: [po, ux-design-expert, architect]

  - id: scope
    title: Scope
    type: free-text
    instruction: |
      Define the boundaries of this story:
      - What is included in this story
      - What is explicitly excluded
      - Dependencies on other stories
      - Deliverables that will be used by downstream stories
    example: |
      Create comprehensive persona definitions that will be used by:
      - Story 6.1.2 (Agent File Updates)
      - Story 6.1.3 (@docs Agent Creation)
      - Story 6.1.4 (Configuration System)
    elicit: true
    owner: po
    editors: [po, ux-design-expert, architect]

  - id: coderabbit-integration
    title: 🤖 CodeRabbit Integration
    instruction: |
      Define quality gates and specialized agent assignments for design/research work.
      Even though this is not code, quality standards still apply.
    elicit: true
    owner: po
    editors: [po, sm]
    sections:
      - id: story-type-analysis
        title: Story Type Analysis
        instruction: |
          Categorize the design/research story:
          - Documentation/Design: Writing, planning, specifications
          - Research/Analysis: User research, competitive analysis, technical research
          - Architecture: System design, patterns, technical planning
          - UX Design: User experience, interface design, accessibility
          - Strategy: Product strategy, roadmap planning
        template: |
          **Primary Type**: {{story_type}}
          **Secondary Type(s)**: {{story_type_secondary}}
          **Complexity**: {{complexity_level}}
        elicit: true
        owner: po
        editors: [po]

      - id: specialized-agents
        title: Specialized Agent Assignment
        instruction: |
          List which specialized agents should be involved:

          **Design/Research Stories**:
          - @ux-design-expert: UX design, user research, accessibility
          - @architect: Architecture design, technical planning, patterns
          - @analyst: Research, competitive analysis, data analysis
          - @po: Requirements validation, acceptance criteria
          - @qa: Quality review of deliverables

          **Supporting Agents**:
          - @pm: Strategy alignment, roadmap planning
          - @sm: Process facilitation, sprint planning
        template: |
          **Primary Agents**:
          - {{primary_agent_1}}
          - {{primary_agent_2}}

          **Supporting Agents**:
          - {{supporting_agent_1}}
          - {{supporting_agent_2}}
        elicit: true
        owner: po
        editors: [po, sm]

      - id: quality-gates
        title: Quality Gate Tasks
        instruction: |
          Define validation checkpoints for design/research work:

          **Pre-Completion Review** (Primary Agent):
          - Validate deliverables meet acceptance criteria
          - Check completeness and consistency
          - Cultural sensitivity review (if applicable)

          **Documentation Review** (Architect/Analyst):
          - Ensure technical accuracy
          - Validate against source documents
          - Check format and structure

          **Handoff Validation** (PO):
          - Verify downstream stories can use deliverables
          - Confirm no blocking issues
          - Validate acceptance criteria coverage
        template: |
          - [ ] Pre-Completion Review (@{{primary_agent}}): Validate deliverables before marking complete
          - [ ] Documentation Review (@architect or @analyst): Ensure technical accuracy
          - [ ] Handoff Validation (@po): Verify downstream story readiness
        elicit: true
        owner: po
        editors: [po, sm]

      - id: focus-areas
        title: Quality Focus Areas
        instruction: |
          Specific quality criteria based on story type:

          **Documentation/Design Stories**:
          - Clarity and completeness
          - Consistency across all deliverables
          - Proper structure and formatting

          **Research Stories**:
          - Source verification and citations
          - Data accuracy and validation
          - Methodology documentation

          **Architecture Stories**:
          - Technical accuracy
          - Alignment with existing patterns
          - Scalability and maintainability considerations

          **UX Design Stories**:
          - Accessibility compliance (WCAG 2.1 AA)
          - User-centered design principles
          - Consistency with design system
        template: |
          **Primary Focus**:
          - {{focus_area_1}}
          - {{focus_area_2}}

          **Secondary Focus**:
          - {{focus_area_3}}
          - {{focus_area_4}}
        elicit: true
        owner: po
        editors: [po]

  - id: tasks-breakdown
    title: Tasks Breakdown
    type: structured-list
    instruction: |
      Break down the story into time-boxed phases and tasks.
      For design/research work, structure by research phases, design iterations, or deliverable creation.

      Format:
      ### Phase N: Phase Name (X hours)
      **Task N.M: Task Name** (X hours)
      - Bullet point details
      - Expected outputs
    example: |
      ### Day 1: Research & Design (8 hours)

      **Task 1.1: User Research** (3 hours)
      - Conduct 5 user interviews
      - Analyze pain points and needs
      - Document research findings

      **Task 1.2: Design Exploration** (3 hours)
      - Create 3 design concepts
      - Review with stakeholders
      - Select preferred direction

      **Task 1.3: Detailed Design** (2 hours)
      - Create high-fidelity mockups
      - Document design decisions
      - Prepare for handoff
    elicit: true
    owner: ux-design-expert
    editors: [ux-design-expert, architect, analyst, po]

  - id: testing-validation
    title: Testing & Validation
    type: structured-text
    instruction: |
      Define how the deliverables will be validated and tested.
      Include validation steps, success criteria, and iteration criteria.
    elicit: true
    owner: ux-design-expert
    editors: [ux-design-expert, architect, qa]
    sections:
      - id: validation-steps
        title: Validation Steps
        instruction: |
          Define specific validation checkpoints by phase:
          - What will be validated
          - Who will validate it
          - Success criteria for each validation
        template: |
          **Phase 1 Validation (After Research):**
          - [ ] **Research Quality Check:** Verify research methodology and data accuracy
          - [ ] **Stakeholder Review:** Present findings to 3+ stakeholders for feedback
          - [ ] **Documentation Check:** Ensure all research is properly documented

          **Phase 2 Validation (After Design/Deliverables):**
          - [ ] **Quality Review:** Validate deliverables meet acceptance criteria
          - [ ] **Consistency Check:** Verify consistency across all outputs
          - [ ] **Handoff Validation:** Confirm downstream teams can use deliverables
        elicit: true
        owner: ux-design-expert
        editors: [ux-design-expert, qa]

      - id: success-criteria
        title: Success Criteria
        instruction: |
          Define measurable success criteria for validation:
          - Quality metrics (e.g., 4.5/5 stars from reviews)
          - Completeness metrics (e.g., 100% of deliverables complete)
          - Usability metrics (e.g., downstream teams need zero clarifications)
        template: |
          - **Quality:** {{quality_metric}}
          - **Completeness:** {{completeness_metric}}
          - **Usability:** {{usability_metric}}
          - **Accuracy:** {{accuracy_metric}}
        elicit: true
        owner: qa
        editors: [qa, po]

      - id: iteration-criteria
        title: Review & Iteration Criteria
        instruction: |
          Define what constitutes minor vs. major changes vs. complete redo:

          **Minor Changes:** Quick fixes (30 min - 1 hour)
          **Major Changes:** Significant rework (2-4 hours)
          **Complete Redo:** Fundamental approach rejected (escalate to PO)
        template: |
          **Minor Changes ({{minor_time_estimate}}):**
          - {{minor_change_example_1}}
          - {{minor_change_example_2}}

          **Major Changes ({{major_time_estimate}}):**
          - {{major_change_example_1}}
          - {{major_change_example_2}}

          **Complete Redo (Escalate to PO):**
          - {{redo_trigger_1}}
          - {{redo_trigger_2}}
        elicit: true
        owner: ux-design-expert
        editors: [ux-design-expert, po]

  - id: acceptance-criteria
    title: Acceptance Criteria
    type: categorized-list
    instruction: |
      Copy and expand acceptance criteria from the parent epic.
      Categorize into Must Have, Should Have, and Nice to Have.
    elicit: true
    owner: po
    editors: [po]
    sections:
      - id: must-have
        title: Must Have
        instruction: Critical requirements that must be met for story completion
        type: checklist
        elicit: true

      - id: should-have
        title: Should Have
        instruction: Important requirements that significantly improve quality
        type: checklist
        elicit: true

      - id: nice-to-have
        title: Nice to Have
        instruction: Optional enhancements that add value but aren't required
        type: checklist
        elicit: true

  - id: dependencies
    title: Dependencies
    type: structured-list
    instruction: |
      Document dependencies and blocking relationships:
      - Prerequisites: What must be complete before this story starts
      - Dependent Stories: What stories are blocked by this story
      - External Dependencies: Third-party tools, stakeholder input, etc.
    template: |
      ### Prerequisites (Blocking)
      - **Story X.Y:** Brief description of why this blocks
      - **External:** Tool/stakeholder needed

      ### Dependent Stories (This Blocks)
      - **Story X.Y:** What they need from this story
      - **Epic X:** How this epic depends on these deliverables
    elicit: true
    owner: po
    editors: [po, sm]

  - id: deliverables
    title: Deliverables
    type: structured-list
    instruction: |
      List all deliverables with clear specifications:
      - File locations and formats
      - Content requirements
      - Examples of expected output
      - How deliverables will be used by downstream stories
    example: |
      ### 1. Persona Definitions Document
      **Location:** `docs/agents/persona-definitions.md`

      **Contents:**
      - Complete persona for each agent
      - Name, role, archetype, color, icon
      - Communication style and traits
      - Design rationale

      ### 2. YAML Export
      **Location:** `docs/agents/persona-definitions.yaml`

      **Format:**
      ```yaml
      agents:
        - id: dev
          name: Dex
          role: Builder
          archetype: Aquarius
      ```
    elicit: true
    owner: ux-design-expert
    editors: [ux-design-expert, architect]

  - id: investment-breakdown
    title: Investment Breakdown
    type: structured-text
    instruction: |
      Break down the time and cost investment:
      - Research phase hours and cost
      - Design phase hours and cost
      - Documentation phase hours and cost
      - Total investment
    template: |
      - **Research & Analysis:** {{research_hours}} hours @ ${{hourly_rate}}/hr = ${{research_cost}}
      - **Design & Creation:** {{design_hours}} hours @ ${{hourly_rate}}/hr = ${{design_cost}}
      - **Documentation:** {{doc_hours}} hours @ ${{hourly_rate}}/hr = ${{doc_cost}}
      - **Total:** ${{total_cost}} ({{duration}} @ ${{daily_rate}}/day story rate)
    elicit: true
    owner: po
    editors: [po, pm]

  - id: success-metrics
    title: Success Metrics
    type: bullet-list
    instruction: |
      Define measurable success metrics for the story:
      - Quality metrics (ratings, approvals)
      - Adoption metrics (usage by downstream stories)
      - Performance metrics (time saved, efficiency gained)
      - User satisfaction metrics
    example: |
      - **Quality:** 5/5 stars from team review
      - **Cultural Sensitivity:** 100% approval from diverse reviewers
      - **Usability:** Deliverables used by downstream stories without rework
      - **Accessibility:** Passes WCAG AA standards
    elicit: true
    owner: po
    editors: [po, qa]

  - id: risks-mitigation
    title: Risks & Mitigation
    type: structured-list
    instruction: |
      Identify risks specific to design/research work and mitigation strategies.

      For each risk, document:
      - Risk description
      - Likelihood (Low/Medium/High)
      - Impact (Low/Medium/High)
      - Mitigation strategy
    template: |
      ### Risk 1: {{risk_title}}
      - **Likelihood:** {{likelihood}}
      - **Impact:** {{impact}}
      - **Mitigation:** {{mitigation_strategy}}
    elicit: true
    owner: po
    editors: [po, pm]

  - id: dev-notes
    title: Dev Notes
    instruction: |
      Provide contextual information for implementers:
      - Design principles and rationale
      - Source files and references
      - Research findings summary
      - Important constraints or considerations
    elicit: true
    owner: ux-design-expert
    editors: [ux-design-expert, architect]
    sections:
      - id: design-principles
        title: Design Principles Applied
        instruction: Document key design principles guiding this work
        elicit: true

      - id: source-references
        title: Source Files & References
        instruction: |
          List all source documents and references:
          - Primary source documents (epics, PRDs, decisions)
          - Current files to reference or modify
          - Research sources and citations
          - External tools or resources needed
        elicit: true

  - id: related-documents
    title: Related Documents
    type: link-list
    instruction: Link to related epics, decisions, and reference materials
    template: |
      - **Epic:** [Epic {{epic_num}} - {{epic_title}}](../epics/epic-{{epic_num}}-{{epic_slug}}.md)
      - **Decision:** [Decision #{{decision_num}} - {{decision_title}}](../one-pagers/DECISION-{{decision_num}}-{{decision_slug}}.md)
      - **Research:** {{research_references}}
    elicit: true
    owner: po
    editors: [po]

  - id: change-log
    title: Change Log
    type: table
    columns: [Date, Version, Description, Author]
    instruction: Track changes made to this story document
    owner: po
    editors: [po, ux-design-expert, architect, qa]

  - id: dev-agent-record
    title: Dev Agent Record
    instruction: This section is populated by the implementing agent during execution
    owner: implementing-agent
    editors: [ux-design-expert, architect, analyst]
    sections:
      - id: agent-model
        title: Agent Model Used
        template: "{{agent_model_name_version}}"
        instruction: Record the specific AI agent model and version used
        owner: implementing-agent
        editors: [implementing-agent]

      - id: debug-log-references
        title: Debug Log References
        instruction: Reference any debug logs or traces generated during work
        owner: implementing-agent
        editors: [implementing-agent]

      - id: completion-notes
        title: Completion Notes
        instruction: Notes about completion, issues encountered, decisions made
        owner: implementing-agent
        editors: [implementing-agent]

      - id: file-list
        title: File List
        instruction: List all files created, modified, or referenced during story execution
        owner: implementing-agent
        editors: [implementing-agent]

  - id: qa-results
    title: QA Results
    instruction: Results from QA review of the completed story deliverables
    owner: qa
    editors: [qa]
    template: |
      ### Quality Review Summary
      **Reviewer:** @qa ({{qa_agent_name}})
      **Review Date:** {{review_date}}
      **Overall Score:** {{score}}/10

      ### Deliverables Validation
      - [ ] All deliverables present and complete
      - [ ] Quality meets acceptance criteria
      - [ ] Downstream stories can use deliverables
      - [ ] Documentation is clear and accurate

      ### Issues Found
      {{issues_list}}

      ### Recommendations
      {{recommendations}}

      ### Approval Status
      {{approval_status}}

metadata:
  template_type: design-story
  compatible_agents:
    - ux-design-expert
    - architect
    - analyst
    - po
    - qa
  incompatible_agents:
    - dev
    - github-devops
  story_types:
    - design
    - research
    - architecture
    - documentation
    - planning
  version_history:
    - version: 1.0
      date: 2025-01-14
      author: "@po (Pax)"
      changes: "Initial design story template based on Story 6.1.1 hybrid approach"