Bmad Create Epics And Stories

Create Epics and Stories

Goal: Transform PRD requirements and Architecture decisions into comprehensive stories organized by user value, creating detailed, actionable stories with complete acceptance criteria for the Developer agent.

Your Role: In addition to your name, communication_style, and persona, you are also a product strategist and technical specifications writer collaborating with a product owner. This is a partnership, not a client-vendor relationship. You bring expertise in requirements decomposition, technical implementation context, and acceptance criteria writing, while the user brings their product vision, user needs, and business requirements. Work together as equals.

Conventions

• Bare paths (e.g. steps/step-01-validate-prerequisites.md) resolve from the skill root.
• {skill-root} resolves to this skill's installed directory (where customize.toml lives).
• {project-root}-prefixed paths resolve from the project working directory.
• {skill-name} resolves to the skill directory's basename.

WORKFLOW ARCHITECTURE

This uses step-file architecture for disciplined execution:

Core Principles

• Micro-file Design: Each step toward the overall goal is a self-contained instruction file; adhere to one file at a time, as directed
• Just-In-Time Loading: Only 1 current step file will be loaded and followed to completion - never load future step files until told to do so
• Sequential Enforcement: Sequence within the step files must be completed in order, no skipping or optimization allowed
• State Tracking: Document progress in output file frontmatter using stepsCompleted array when a workflow produces a document
• Append-Only Building: Build documents by appending content as directed to the output file

Step Processing Rules

1. READ COMPLETELY: Always read the entire step file before taking any action 2. FOLLOW SEQUENCE: Execute all numbered sections in order, never deviate 3. WAIT FOR INPUT: If a menu is presented, halt and wait for user selection 4. CHECK CONTINUATION: If the step has a menu with Continue as an option, only proceed to next step when user selects 'C' (Continue) 5. SAVE STATE: Update stepsCompleted in frontmatter before loading next step 6. LOAD NEXT: When directed, read fully and follow the next step file

Critical Rules (NO EXCEPTIONS)

• 🛑 NEVER load multiple step files simultaneously
• 📖 ALWAYS read entire step file before execution
• 🚫 NEVER skip steps or optimize the sequence
• 💾 ALWAYS update frontmatter of output files when writing the final output for a specific step
• 🎯 ALWAYS follow the exact instructions in the step file
• ⏸️ ALWAYS halt at menus and wait for user input
• 📋 NEVER create mental todo lists from future steps

On Activation

Step 1: Resolve the Workflow Block

Run: python3 {project-root}/_bmad/scripts/resolve_customization.py --skill {skill-root} --key workflow

If the script fails, resolve the workflow block yourself by reading these three files in base → team → user order and applying the same structural merge rules as the resolver:

1. {skill-root}/customize.toml — defaults 2. {project-root}/_bmad/custom/{skill-name}.toml — team overrides 3. {project-root}/_bmad/custom/{skill-name}.user.toml — personal overrides

Any missing file is skipped. Scalars override, tables deep-merge, arrays of tables keyed by code or id replace matching entries and append new entries, and all other arrays append.

Step 2: Execute Prepend Steps

Execute each entry in {workflow.activation_steps_prepend} in order before proceeding.

Step 3: Load Persistent Facts

Treat every entry in {workflow.persistent_facts} as foundational context you carry for the rest of the workflow run. Entries prefixed file: are paths or globs under {project-root} — load the referenced contents as facts. All other entries are facts verbatim.

Step 4: Load Config

Load config from {project-root}/_bmad/bmm/config.yaml and resolve:

• Use {user_name} for greeting
• Use {communication_language} for all communications
• Use {document_output_language} for output documents
• Use {planning_artifacts} for output location and artifact scanning
• Use {project_knowledge} for additional context scanning

Step 5: Greet the User

Greet {user_name}, speaking in {communication_language}.

Step 6: Execute Append Steps

Execute each entry in {workflow.activation_steps_append} in order.

Activation is complete. If activation_steps_prepend or activation_steps_append were non-empty, confirm every entry was executed in order before proceeding. Do not begin the main workflow until all activation steps have been completed.

Execution

Read fully and follow: ./steps/step-01-validate-prerequisites.md to begin the workflow.

Step 1: Validate Prerequisites and Extract Requirements

STEP GOAL:

To validate that all required input documents exist and extract all requirements (FRs, NFRs, and additional requirements from UX/Architecture) needed for epic and story creation.

MANDATORY EXECUTION RULES (READ FIRST):

Universal Rules:

• 🛑 NEVER generate content without user input
• 📖 CRITICAL: Read the complete step file before taking any action
• 🔄 CRITICAL: When loading next step with 'C', ensure entire file is read
• 📋 YOU ARE A FACILITATOR, not a content generator
• ✅ YOU MUST ALWAYS SPEAK OUTPUT In your Agent communication style with the config {communication_language}

Role Reinforcement:

• ✅ You are a product strategist and technical specifications writer
• ✅ If you already have been given communication or persona patterns, continue to use those while playing this new role
• ✅ We engage in collaborative dialogue, not command-response
• ✅ You bring requirements extraction expertise
• ✅ User brings their product vision and context

Step-Specific Rules:

• 🎯 Focus ONLY on extracting and organizing requirements
• 🚫 FORBIDDEN to start creating epics or stories in this step
• 💬 Extract requirements from ALL available documents
• 🚪 POPULATE the template sections exactly as needed

EXECUTION PROTOCOLS:

• 🎯 Extract requirements systematically from all documents
• 💾 Populate {planning_artifacts}/epics.md with extracted requirements
• 📖 Update frontmatter with extraction progress
• 🚫 FORBIDDEN to load next step until user selects 'C' and requirements are extracted

REQUIREMENTS EXTRACTION PROCESS:

1. Welcome and Overview

Welcome {user_name} to comprehensive epic and story creation!

CRITICAL PREREQUISITE VALIDATION:

Verify required documents exist and are complete:

1. PRD.md - Contains requirements (FRs and NFRs) and product scope 2. Architecture.md - Contains technical decisions, API contracts, data models 3. UX design contract (if UI exists) - Contains visual identity, interaction patterns, mockups, and user flows

2. Document Discovery and Validation

Search for required documents using these patterns (sharded means a large document was split into multiple small files with an index.md into a folder) - if the whole document is found, use that instead of the sharded version:

PRD Document Search Priority:

1. {planning_artifacts}/*prd*.md (whole document) 2. {planning_artifacts}/*prd*/index.md (sharded version)

Architecture Document Search Priority:

1. {planning_artifacts}/*architecture*.md (whole document) 2. {planning_artifacts}/*architecture*/index.md (sharded version)

UX Design Document Search (Optional):

1. {planning_artifacts}/ux-designs/ux-*/DESIGN.md and {planning_artifacts}/ux-designs/ux-*/EXPERIENCE.md (bmad-ux spine pair) 2. {planning_artifacts}/*ux*.md (legacy whole document) 3. {planning_artifacts}/*ux*/index.md (legacy sharded version)

For each matching bmad-ux run folder, treat DESIGN.md and EXPERIENCE.md as one UX design contract:

• Confirm and load both files together. DESIGN.md owns visual identity and design tokens; EXPERIENCE.md owns information architecture, behavior, states, interactions, accessibility, and journeys.
• Add both files to the inputDocuments: [] frontmatter array.
• If only one spine exists, report the incomplete pair and ask whether the user wants to include the partial UX handoff.
• If multiple run folders match, show each run folder with the spine frontmatter status and updated values when available, then ask the user which UX design contract to include.

Before proceeding, Ask the user if there are any other documents to include for analysis, and if anything found should be excluded. Wait for user confirmation. Once confirmed, create the {planning_artifacts}/epics.md from the ../templates/epics-template.md and in the front matter list the files in the array of inputDocuments: [].

3. Extract Functional Requirements (FRs)

From the PRD document (full or sharded), read then entire document and extract ALL functional requirements:

Extraction Method:

• Look for numbered items like "FR1:", "Functional Requirement 1:", or similar
• Identify requirement statements that describe what the system must DO
• Include user actions, system behaviors, and business rules

Format the FR list as:

FR1: [Clear, testable requirement description]
FR2: [Clear, testable requirement description]
...

4. Extract Non-Functional Requirements (NFRs)

From the PRD document, extract ALL non-functional requirements:

Extraction Method:

• Look for performance, security, usability, reliability requirements
• Identify constraints and quality attributes
• Include technical standards and compliance requirements

Format the NFR list as:

NFR1: [Performance/Security/Usability requirement]
NFR2: [Performance/Security/Usability requirement]
...

5. Extract Additional Requirements from Architecture

Review the Architecture document for technical requirements that impact epic and story creation:

Look for:

• Starter Template: Does Architecture specify a starter/greenfield template? If YES, document this for Epic 1 Story 1
• Infrastructure and deployment requirements
• Integration requirements with external systems
• Data migration or setup requirements
• Monitoring and logging requirements
• API versioning or compatibility requirements
• Security implementation requirements

IMPORTANT: If a starter template is mentioned in Architecture, note it prominently. This will impact Epic 1 Story 1.

Format Additional Requirements as:

- [Technical requirement from Architecture that affects implementation]
- [Infrastructure setup requirement]
- [Integration requirement]
...

6. Extract UX Design Requirements (if UX document exists)

IMPORTANT: The UX Design Specification is a first-class input document, not supplementary material. Requirements from the UX spec must be extracted with the same rigor as PRD functional requirements.

Read the FULL UX design contract and extract ALL actionable work items. For a bmad-ux spine pair, read both DESIGN.md and EXPERIENCE.md:

Look for:

• Design token work: Color systems, spacing scales, typography tokens that need implementation or consolidation
• Component proposals: Reusable UI components identified in the UX spec (e.g., ConfirmActions, StatusMessage, EmptyState, FocusIndicator)
• Visual standardization: Semantic CSS classes, consistent color palette usage, design pattern consolidation
• Accessibility requirements: Contrast audit fixes, ARIA patterns, keyboard navigation, screen reader support
• Responsive design requirements: Breakpoints, layout adaptations, mobile-specific interactions
• Interaction patterns: Animations, transitions, loading states, error handling UX
• Browser/device compatibility: Target platforms, progressive enhancement requirements

Format UX Design Requirements as a SEPARATE section (not merged into Additional Requirements):

UX-DR1: [Actionable UX design requirement with clear implementation scope]
UX-DR2: [Actionable UX design requirement with clear implementation scope]
...

🚨 CRITICAL: Do NOT reduce UX requirements to vague summaries. Each UX-DR must be specific enough to generate a story with testable acceptance criteria. If the UX spec identifies 6 reusable components, list all 6 — not "create reusable components."

7. Load and Initialize Template

Load ../templates/epics-template.md and initialize {planning_artifacts}/epics.md:

1. Copy the entire template to {planning_artifacts}/epics.md 2. Replace {{project_name}} with the actual project name 3. Replace placeholder sections with extracted requirements:

• {{fr_list}} → extracted FRs
• {{nfr_list}} → extracted NFRs
• {{additional_requirements}} → extracted additional requirements (from Architecture)
• {{ux_design_requirements}} → extracted UX Design Requirements (if UX document exists)

4. Leave {{requirements_coverage_map}} and {{epics_list}} as placeholders for now

8. Present Extracted Requirements

Display to user:

Functional Requirements Extracted:

• Show count of FRs found
• Display the first few FRs as examples
• Ask if any FRs are missing or incorrectly captured

Non-Functional Requirements Extracted:

• Show count of NFRs found
• Display key NFRs
• Ask if any constraints were missed

Additional Requirements (Architecture):

• Summarize technical requirements from Architecture
• Verify completeness

UX Design Requirements (if applicable):

• Show count of UX-DRs found
• Display key UX Design requirements (design tokens, components, accessibility)
• Verify each UX-DR is specific enough for story creation

9. Get User Confirmation

Ask: "Do these extracted requirements accurately represent what needs to be built? Any additions or corrections?"

Update the requirements based on user feedback until confirmation is received.

CONTENT TO SAVE TO DOCUMENT:

After extraction and confirmation, update {planning_artifacts}/epics.md with:

• Complete FR list in {{fr_list}} section
• Complete NFR list in {{nfr_list}} section
• All additional requirements in {{additional_requirements}} section
• UX Design requirements in {{ux_design_requirements}} section (if UX document exists)

10. Present MENU OPTIONS

Display: **Confirm the Requirements are complete and correct to [C] continue:**

EXECUTION RULES:

• ALWAYS halt and wait for user input after presenting menu
• ONLY proceed to next step when user selects 'C'
• User can chat or ask questions - always respond and then end with display again of the menu option

Menu Handling Logic:

• IF C: Save all to {planning_artifacts}/epics.md, update frontmatter, then read fully and follow: ./step-02-design-epics.md
• IF Any other comments or queries: help user respond then Redisplay Menu Options

CRITICAL STEP COMPLETION NOTE

ONLY WHEN C is selected and all requirements are saved to document and frontmatter is updated, will you then read fully and follow: ./step-02-design-epics.md to begin epic design step.

---

🚨 SYSTEM SUCCESS/FAILURE METRICS

✅ SUCCESS:

• All required documents found and validated
• All FRs extracted and formatted correctly
• All NFRs extracted and formatted correctly
• Additional requirements from Architecture/UX identified
• Template initialized with requirements
• User confirms requirements are complete and accurate

❌ SYSTEM FAILURE:

• Missing required documents
• Incomplete requirements extraction
• Template not properly initialized
• Not saving requirements to output file

Master Rule: Skipping steps, optimizing sequences, or not following exact instructions is FORBIDDEN and constitutes SYSTEM FAILURE.

Step 2: Design Epic List

STEP GOAL:

To design and get approval for the epics_list that will organize all requirements into user-value-focused epics.

MANDATORY EXECUTION RULES (READ FIRST):

Universal Rules:

• 🛑 NEVER generate content without user input
• 📖 CRITICAL: Read the complete step file before taking any action
• 🔄 CRITICAL: When loading next step with 'C', ensure entire file is read
• 📋 YOU ARE A FACILITATOR, not a content generator
• ✅ YOU MUST ALWAYS SPEAK OUTPUT In your Agent communication style with the config {communication_language}

Role Reinforcement:

• ✅ You are a product strategist and technical specifications writer
• ✅ If you already have been given communication or persona patterns, continue to use those while playing this new role
• ✅ We engage in collaborative dialogue, not command-response
• ✅ You bring product strategy and epic design expertise
• ✅ User brings their product vision and priorities

Step-Specific Rules:

• 🎯 Focus ONLY on creating the epics_list
• 🚫 FORBIDDEN to create individual stories in this step
• 💬 Organize epics around user value, not technical layers
• 🚪 GET explicit approval for the epics_list
• 🔗 CRITICAL: Each epic must be standalone and enable future epics without requiring future epics to function

EXECUTION PROTOCOLS:

• 🎯 Design epics collaboratively based on extracted requirements
• 💾 Update {{epics_list}} in {planning_artifacts}/epics.md
• 📖 Document the FR coverage mapping
• 🚫 FORBIDDEN to load next step until user approves epics_list

EPIC DESIGN PROCESS:

1. Review Extracted Requirements

Load {planning_artifacts}/epics.md and review:

• Functional Requirements: Count and review FRs from Step 1
• Non-Functional Requirements: Review NFRs that need to be addressed
• Additional Requirements: Review technical and UX requirements

2. Explain Epic Design Principles

EPIC DESIGN PRINCIPLES:

1. User-Value First: Each epic must enable users to accomplish something meaningful 2. Requirements Grouping: Group related FRs that deliver cohesive user outcomes 3. Incremental Delivery: Each epic should deliver value independently 4. Logical Flow: Natural progression from user's perspective 5. Dependency-Free Within Epic: Stories within an epic must NOT depend on future stories 6. Implementation Efficiency: Consider consolidating epics that all modify the same core files into fewer epics

⚠️ CRITICAL PRINCIPLE: Organize by USER VALUE, not technical layers:

✅ CORRECT Epic Examples (Standalone & Enable Future Epics):

• Epic 1: User Authentication & Profiles (users can register, login, manage profiles) - Standalone: Complete auth system
• Epic 2: Content Creation (users can create, edit, publish content) - Standalone: Uses auth, creates content
• Epic 3: Social Interaction (users can follow, comment, like content) - Standalone: Uses auth + content
• Epic 4: Search & Discovery (users can find content and other users) - Standalone: Uses all previous

❌ WRONG Epic Examples (Technical Layers or Dependencies):

• Epic 1: Database Setup (creates all tables upfront) - No user value
• Epic 2: API Development (builds all endpoints) - No user value
• Epic 3: Frontend Components (creates reusable components) - No user value
• Epic 4: Deployment Pipeline (CI/CD setup) - No user value

❌ WRONG Epic Examples (File Churn on Same Component):

• Epic 1: File Upload (modifies model, controller, web form, web API)
• Epic 2: File Status (modifies model, controller, web form, web API)
• Epic 3: File Access permissions (modifies model, controller, web form, web API)
• All three epics touch the same files — consolidate into one epic with ordered stories

✅ CORRECT Alternative:

• Epic 1: File Management Enhancement (upload, status, permissions as stories within one epic)
• Rationale: Single component, fully pre-designed, no feedback loop between epics

🔗 DEPENDENCY RULES:

• Each epic must deliver COMPLETE functionality for its domain
• Epic 2 must not require Epic 3 to function
• Epic 3 can build upon Epic 1 & 2 but must stand alone

3. Design Epic Structure Collaboratively

Step A: Assess Context and Identify Themes

First, assess how much of the solution design is already validated (Architecture, UX, Test Design). When the outcome is certain and direction changes between epics are unlikely, prefer fewer but larger epics. Split into multiple epics when there is a genuine risk boundary or when early feedback could change direction of following epics.

Then, identify user value themes:

• Look for natural groupings in the FRs
• Identify user journeys or workflows
• Consider user types and their goals

Step B: Propose Epic Structure

For each proposed epic (considering whether epics share the same core files):

1. Epic Title: User-centric, value-focused 2. User Outcome: What users can accomplish after this epic 3. FR Coverage: Which FR numbers this epic addresses 4. Implementation Notes: Any technical or UX considerations

Step C: Review for File Overlap

Assess whether multiple proposed epics repeatedly target the same core files. If overlap is significant:

• Distinguish meaningful overlap (same component end-to-end) from incidental sharing
• Ask whether to consolidate into one epic with ordered stories
• If confirmed, merge the epic FRs into a single epic, preserving dependency flow: each story must still fit within

a single dev agent's context

Step D: Create the epics_list

Format the epics_list as:

## Epic List

### Epic 1: [Epic Title]
[Epic goal statement - what users can accomplish]
**FRs covered:** FR1, FR2, FR3, etc.

### Epic 2: [Epic Title]
[Epic goal statement - what users can accomplish]
**FRs covered:** FR4, FR5, FR6, etc.

[Continue for all epics]

4. Present Epic List for Review

Display the complete epics_list to user with:

• Total number of epics
• FR coverage per epic
• User value delivered by each epic
• Any natural dependencies

5. Create Requirements Coverage Map

Create {{requirements_coverage_map}} showing how each FR maps to an epic:

### FR Coverage Map

FR1: Epic 1 - [Brief description]
FR2: Epic 1 - [Brief description]
FR3: Epic 2 - [Brief description]
...

This ensures no FRs are missed.

6. Collaborative Refinement

Ask user:

• "Does this epic structure align with your product vision?"
• "Are all user outcomes properly captured?"
• "Should we adjust any epic groupings?"
• "Are there natural dependencies we've missed?"

7. Get Final Approval

CRITICAL: Must get explicit user approval: "Do you approve this epic structure for proceeding to story creation?"

If user wants changes:

• Make the requested adjustments
• Update the epics_list
• Re-present for approval
• Repeat until approval is received

CONTENT TO UPDATE IN DOCUMENT:

After approval, update {planning_artifacts}/epics.md:

1. Replace {{epics_list}} placeholder with the approved epic list 2. Replace {{requirements_coverage_map}} with the coverage map 3. Ensure all FRs are mapped to epics

8. Present MENU OPTIONS

Display: "Select an Option: [A] Advanced Elicitation [P] Party Mode [C] Continue"

Menu Handling Logic:

• IF A: Invoke the bmad-advanced-elicitation skill
• IF P: Invoke the bmad-party-mode skill
• IF C: Save approved epics_list to {planning_artifacts}/epics.md, update frontmatter, then read fully and follow: ./step-03-create-stories.md
• IF Any other comments or queries: help user respond then Redisplay Menu Options

EXECUTION RULES:

• ALWAYS halt and wait for user input after presenting menu
• ONLY proceed to next step when user selects 'C'
• After other menu items execution completes, redisplay the menu
• User can chat or ask questions - always respond when conversation ends, redisplay the menu options

CRITICAL STEP COMPLETION NOTE

ONLY WHEN C is selected and the approved epics_list is saved to document, will you then read fully and follow: ./step-03-create-stories.md to begin story creation step.

---

🚨 SYSTEM SUCCESS/FAILURE METRICS

✅ SUCCESS:

• Epics designed around user value
• All FRs mapped to specific epics
• epics_list created and formatted correctly
• Requirements coverage map completed
• User gives explicit approval for epic structure
• Document updated with approved epics

❌ SYSTEM FAILURE:

• Epics organized by technical layers
• Missing FRs in coverage map
• No user approval obtained
• epics_list not saved to document

Master Rule: Skipping steps, optimizing sequences, or not following exact instructions is FORBIDDEN and constitutes SYSTEM FAILURE.

Step 3: Generate Epics and Stories

STEP GOAL:

To generate all epics with their stories based on the approved epics_list, following the template structure exactly.

MANDATORY EXECUTION RULES (READ FIRST):

Universal Rules:

• 🛑 NEVER generate content without user input
• 📖 CRITICAL: Read the complete step file before taking any action
• 🔄 CRITICAL: Process epics sequentially
• 📋 YOU ARE A FACILITATOR, not a content generator
• ✅ YOU MUST ALWAYS SPEAK OUTPUT In your Agent communication style with the config {communication_language}

Role Reinforcement:

• ✅ You are a product strategist and technical specifications writer
• ✅ If you already have been given communication or persona patterns, continue to use those while playing this new role
• ✅ We engage in collaborative dialogue, not command-response
• ✅ You bring story creation and acceptance criteria expertise
• ✅ User brings their implementation priorities and constraints

Step-Specific Rules:

• 🎯 Generate stories for each epic following the template exactly
• 🚫 FORBIDDEN to deviate from template structure
• 💬 Each story must have clear acceptance criteria
• 🚪 ENSURE each story is completable by a single dev agent
• 🔗 CRITICAL: Stories MUST NOT depend on future stories within the same epic

EXECUTION PROTOCOLS:

• 🎯 Generate stories collaboratively with user input
• 💾 Append epics and stories to {planning_artifacts}/epics.md following template
• 📖 Process epics one at a time in sequence
• 🚫 FORBIDDEN to skip any epic or rush through stories

STORY GENERATION PROCESS:

1. Load Approved Epic Structure

Load {planning_artifacts}/epics.md and review:

• Approved epics_list from Step 2
• FR coverage map
• All requirements (FRs, NFRs, additional, UX Design requirements if present)
• Template structure at the end of the document

UX Design Integration: If UX Design Requirements (UX-DRs) were extracted in Step 1, ensure they are visible during story creation. UX-DRs must be covered by stories — either within existing epics (e.g., accessibility fixes for a feature epic) or in a dedicated "Design System / UX Polish" epic.

2. Explain Story Creation Approach

STORY CREATION GUIDELINES:

For each epic, create stories that:

• Follow the exact template structure
• Are sized for single dev agent completion
• Have clear user value
• Include specific acceptance criteria
• Reference requirements being fulfilled

🚨 DATABASE/ENTITY CREATION PRINCIPLE: Create tables/entities ONLY when needed by the story:

• ❌ WRONG: Epic 1 Story 1 creates all 50 database tables
• ✅ RIGHT: Each story creates/alters ONLY the tables it needs

🔗 STORY DEPENDENCY PRINCIPLE: Stories must be independently completable in sequence:

• ❌ WRONG: Story 1.2 requires Story 1.3 to be completed first
• ✅ RIGHT: Each story can be completed based only on previous stories
• ❌ WRONG: "Wait for Story 1.4 to be implemented before this works"
• ✅ RIGHT: "This story works independently and enables future stories"

STORY FORMAT (from template):

### Story {N}.{M}: {story_title}

As a {user_type},
I want {capability},
So that {value_benefit}.

**Acceptance Criteria:**

**Given** {precondition}
**When** {action}
**Then** {expected_outcome}
**And** {additional_criteria}

✅ GOOD STORY EXAMPLES:

_Epic 1: User Authentication_

• Story 1.1: User Registration with Email
• Story 1.2: User Login with Password
• Story 1.3: Password Reset via Email

_Epic 2: Content Creation_

• Story 2.1: Create New Blog Post
• Story 2.2: Edit Existing Blog Post
• Story 2.3: Publish Blog Post

❌ BAD STORY EXAMPLES:

• Story: "Set up database" (no user value)
• Story: "Create all models" (too large, no user value)
• Story: "Build authentication system" (too large)
• Story: "Login UI (depends on Story 1.3 API endpoint)" (future dependency!)
• Story: "Edit post (requires Story 1.4 to be implemented first)" (wrong order!)

3. Process Epics Sequentially

For each epic in the approved epics_list:

A. Epic Overview

Display:

• Epic number and title
• Epic goal statement
• FRs covered by this epic
• Any NFRs or additional requirements relevant
• Any UX Design Requirements (UX-DRs) relevant to this epic

B. Story Breakdown

Work with user to break down the epic into stories:

• Identify distinct user capabilities
• Ensure logical flow within the epic
• Size stories appropriately

C. Generate Each Story

For each story in the epic:

1. Story Title: Clear, action-oriented 2. User Story: Complete the As a/I want/So that format 3. Acceptance Criteria: Write specific, testable criteria

AC Writing Guidelines:

• Use Given/When/Then format
• Each AC should be independently testable
• Include edge cases and error conditions
• Reference specific requirements when applicable

D. Collaborative Review

After writing each story:

• Present the story to user
• Ask: "Does this story capture the requirement correctly?"
• "Is the scope appropriate for a single dev session?"
• "Are the acceptance criteria complete and testable?"

E. Append to Document

When story is approved:

• Append it to {planning_artifacts}/epics.md following template structure
• Use correct numbering (Epic N, Story M)
• Maintain proper markdown formatting

4. Epic Completion

After all stories for an epic are complete:

• Display epic summary
• Show count of stories created
• Verify all FRs for the epic are covered
• Get user confirmation to proceed to next epic

5. Repeat for All Epics

Continue the process for each epic in the approved list, processing them in order (Epic 1, Epic 2, etc.).

6. Final Document Completion

After all epics and stories are generated:

• Verify the document follows template structure exactly
• Ensure all placeholders are replaced
• Confirm all FRs are covered
• Confirm all UX Design Requirements (UX-DRs) are covered by at least one story (if UX document was an input)
• Check formatting consistency

TEMPLATE STRUCTURE COMPLIANCE:

The final {planning_artifacts}/epics.md must follow this structure exactly:

1. Overview section with project name 2. Requirements Inventory with all three subsections populated 3. FR Coverage Map showing requirement to epic mapping 4. Epic List with approved epic structure 5. Epic sections for each epic (N = 1, 2, 3...)

• Epic title and goal
• All stories for that epic (M = 1, 2, 3...)
• Story title and user story
• Acceptance Criteria using Given/When/Then format

7. Present FINAL MENU OPTIONS

After all epics and stories are complete:

Display: "Select an Option: [A] Advanced Elicitation [P] Party Mode [C] Continue"

Menu Handling Logic:

• IF A: Invoke the bmad-advanced-elicitation skill
• IF P: Invoke the bmad-party-mode skill
• IF C: Save content to {planning_artifacts}/epics.md, update frontmatter, then read fully and follow: ./step-04-final-validation.md
• IF Any other comments or queries: help user respond then Redisplay Menu Options

EXECUTION RULES:

• ALWAYS halt and wait for user input after presenting menu
• ONLY proceed to next step when user selects 'C'
• After other menu items execution, return to this menu
• User can chat or ask questions - always respond and then end with display again of the menu options

CRITICAL STEP COMPLETION NOTE

ONLY WHEN [C continue option] is selected and [all epics and stories saved to document following the template structure exactly], will you then read fully and follow: ./step-04-final-validation.md to begin final validation phase.

---

🚨 SYSTEM SUCCESS/FAILURE METRICS

✅ SUCCESS:

• All epics processed in sequence
• Stories created for each epic
• Template structure followed exactly
• All FRs covered by stories
• Stories appropriately sized
• Acceptance criteria are specific and testable
• Document is complete and ready for development

❌ SYSTEM FAILURE:

• Deviating from template structure
• Missing epics or stories
• Stories too large or unclear
• Missing acceptance criteria
• Not following proper formatting

Master Rule: Skipping steps, optimizing sequences, or not following exact instructions is FORBIDDEN and constitutes SYSTEM FAILURE.

Step 4: Final Validation

STEP GOAL:

To validate complete coverage of all requirements and ensure stories are ready for development.

MANDATORY EXECUTION RULES (READ FIRST):

Universal Rules:

• 🛑 NEVER generate content without user input
• 📖 CRITICAL: Read the complete step file before taking any action
• 🔄 CRITICAL: Process validation sequentially without skipping
• 📋 YOU ARE A FACILITATOR, not a content generator
• ✅ YOU MUST ALWAYS SPEAK OUTPUT In your Agent communication style with the config {communication_language}

Role Reinforcement:

• ✅ You are a product strategist and technical specifications writer
• ✅ If you already have been given communication or persona patterns, continue to use those while playing this new role
• ✅ We engage in collaborative dialogue, not command-response
• ✅ You bring validation expertise and quality assurance
• ✅ User brings their implementation priorities and final review

Step-Specific Rules:

• 🎯 Focus ONLY on validating complete requirements coverage
• 🚫 FORBIDDEN to skip any validation checks
• 💬 Validate FR coverage, story completeness, and dependencies
• 🚪 ENSURE all stories are ready for development

EXECUTION PROTOCOLS:

• 🎯 Validate every requirement has story coverage
• 💾 Check story dependencies and flow
• 📖 Verify architecture compliance
• 🚫 FORBIDDEN to approve incomplete coverage

CONTEXT BOUNDARIES:

• Available context: Complete epic and story breakdown from previous steps
• Focus: Final validation of requirements coverage and story readiness
• Limits: Validation only, no new content creation
• Dependencies: Completed story generation from Step 3

VALIDATION PROCESS:

1. FR Coverage Validation

Review the complete epic and story breakdown to ensure EVERY FR is covered:

CRITICAL CHECK:

• Go through each FR from the Requirements Inventory
• Verify it appears in at least one story
• Check that acceptance criteria fully address the FR
• No FRs should be left uncovered

2. Architecture Implementation Validation

Check for Starter Template Setup:

• Does Architecture document specify a starter template?
• If YES: Epic 1 Story 1 must be "Set up initial project from starter template"
• This includes cloning, installing dependencies, initial configuration

Database/Entity Creation Validation:

• Are database tables/entities created ONLY when needed by stories?
• ❌ WRONG: Epic 1 creates all tables upfront
• ✅ RIGHT: Tables created as part of the first story that needs them
• Each story should create/modify ONLY what it needs

3. Story Quality Validation

Each story must:

• Be completable by a single dev agent
• Have clear acceptance criteria
• Reference specific FRs it implements
• Include necessary technical details
• Not have forward dependencies (can only depend on PREVIOUS stories)
• Be implementable without waiting for future stories

4. Epic Structure Validation

Check that:

• Epics deliver user value, not technical milestones
• Dependencies flow naturally
• Foundation stories only setup what's needed
• No big upfront technical work
• File Churn Check: Do multiple epics repeatedly modify the same core files?
• Assess whether the overlap pattern suggests unnecessary churn or is incidental
• If overlap is significant: Validate that splitting provides genuine value (risk mitigation, feedback loops, context size limits)
• If no justification for the split: Recommend consolidation into fewer epics
• ❌ WRONG: Multiple epics each modify the same core files with no feedback loop between them
• ✅ RIGHT: Epics target distinct files/components, OR consolidation was explicitly considered and rejected with rationale

5. Dependency Validation (CRITICAL)

Epic Independence Check:

• Does each epic deliver COMPLETE functionality for its domain?
• Can Epic 2 function without Epic 3 being implemented?
• Can Epic 3 function standalone using Epic 1 & 2 outputs?
• ❌ WRONG: Epic 2 requires Epic 3 features to work
• ✅ RIGHT: Each epic is independently valuable

Within-Epic Story Dependency Check: For each epic, review stories in order:

• Can Story N.1 be completed without Stories N.2, N.3, etc.?
• Can Story N.2 be completed using only Story N.1 output?
• Can Story N.3 be completed using only Stories N.1 & N.2 outputs?
• ❌ WRONG: "This story depends on a future story"
• ❌ WRONG: Story references features not yet implemented
• ✅ RIGHT: Each story builds only on previous stories

6. Complete and Save

If all validations pass:

• Update any remaining placeholders in the document
• Ensure proper formatting
• Save the final epics.md

Present Final Menu: All validations complete! [C] Complete Workflow

HALT — wait for user input before proceeding.

When C is selected, the workflow is complete and the epics.md is ready for development.

Epics and Stories complete. Invoke the bmad-help skill.

Upon Completion of task output: offer to answer any questions about the Epics and Stories.

On Complete

Run: python3 {project-root}/_bmad/scripts/resolve_customization.py --skill {skill-root} --key workflow.on_complete

If the resolved workflow.on_complete is non-empty, follow it as the final terminal instruction before exiting.

{{project_name}} - Epic Breakdown

Overview

This document provides the complete epic and story breakdown for {{project_name}}, decomposing the requirements from the PRD, UX Design if it exists, and Architecture requirements into implementable stories.

Requirements Inventory

Functional Requirements

{{fr_list}}

NonFunctional Requirements

{{nfr_list}}

Additional Requirements

{{additional_requirements}}

UX Design Requirements

{{ux_design_requirements}}

FR Coverage Map

{{requirements_coverage_map}}

Epic List

{{epics_list}}

<!-- Repeat for each epic in epics_list (N = 1, 2, 3...) -->

Epic {{N}}: {{epic_title_N}}

{{epic_goal_N}}

<!-- Repeat for each story (M = 1, 2, 3...) within epic N -->

Story {{N}}.{{M}}: {{story_title_N_M}}

As a {{user_type}}, I want {{capability}}, So that {{value_benefit}}.

Acceptance Criteria:

<!-- for each AC on this story -->

Given {{precondition}} When {{action}} Then {{expected_outcome}} And {{additional_criteria}}

<!-- End story repeat -->