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.
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.
Explain to {user_name} the epic discovery process using natural dialogue
PRIORITY 1: Check {sprint_status_file} first
Load the FULL file: {sprint_status_file}
Read ALL development_status entries
Find the highest epic number with at least one story marked "done"
Extract epic number from keys like "epic-X-retrospective" or story keys like "X-Y-story-name"
Set {{detected_epic}} = highest epic number found with completed stories
Present finding to user with context
WAIT for {user_name} to confirm or correct
Set {{epic_number}} = {{detected_epic}}
Set {{epic_number}} = user-provided number
PRIORITY 2: Ask user directly
WAIT for {user_name} to provide epic number
Set {{epic_number}} = user-provided number
PRIORITY 3: Fallback to stories folder
Scan {implementation_artifacts} for highest numbered story files
Extract epic numbers from story filenames (pattern: epic-X-Y-story-name.md)
Set {{detected_epic}} = highest epic number found
WAIT for {user_name} to confirm or correct
Set {{epic_number}} = confirmed number
Once {{epic_number}} is determined, verify epic completion status
Find all stories for epic {{epic_number}} in {sprint_status_file}:
- Look for keys starting with "{{epic_number}}-" (e.g., "1-1-", "1-2-", etc.)
- Exclude epic key itself ("epic-{{epic_number}}")
- Exclude retrospective key ("epic-{{epic_number}}-retrospective")
Count total stories found for this epic
Count stories with status = "done"
Collect list of pending story keys (status != "done")
Determine if complete: true if all stories are done, false otherwise
Continue with incomplete epic? (yes/no)
HALT
Set {{partial_retrospective}} = true
Amelia (Developer): "Good point, Charlie. {user_name}, we'll document what we can now, but we may want to revisit after everything's done."
Load input files according to the Input Files table above. For SELECTIVE_LOAD inputs, load only the epic matching {{epic_number}}. For FULL_LOAD inputs, load the complete document. For INDEX_GUIDED inputs, check the index first and load relevant sections. After discovery, these content variables are available: {epics_content} (selective load for this epic), {architecture_content}, {prd_content}, {document_project_content}
After discovery, these content variables are available: {epics_content} (selective load for this epic), {architecture_content}, {prd_content}, {document_project_content}
For each story in epic {{epic_number}}, read the complete story file from {implementation_artifacts}/{{epic_number}}-{{story_num}}-*.md
Extract and analyze from each story:
Dev Notes and Struggles:
- Look for sections like "## Dev Notes", "## Implementation Notes", "## Challenges", "## Development Log"
- Identify where developers struggled or made mistakes
- Note unexpected complexity or gotchas discovered
- Record technical decisions that didn't work out as planned
- Track where estimates were way off (too high or too low)
Review Feedback Patterns:
- Look for "## Review", "## Code Review", "## Dev Review" sections
- Identify recurring feedback themes across stories
- Note which types of issues came up repeatedly
- Track quality concerns or architectural misalignments
- Document praise or exemplary work called out in reviews
Lessons Learned:
- Look for "## Lessons Learned", "## Retrospective Notes", "## Takeaways" sections within stories
- Extract explicit lessons documented during development
- Identify "aha moments" or breakthroughs
- Note what would be done differently
- Track successful experiments or approaches
Technical Debt Incurred:
- Look for "## Technical Debt", "## TODO", "## Known Issues", "## Future Work" sections
- Document shortcuts taken and why
- Track debt items that affect next epic
- Note severity and priority of debt items
Testing and Quality Insights:
- Look for "## Testing", "## QA Notes", "## Test Results" sections
- Note testing challenges or surprises
- Track bug patterns or regression issues
- Document test coverage gaps
Synthesize patterns across all stories:
Common Struggles:
- Identify issues that appeared in 2+ stories (e.g., "3 out of 5 stories had API authentication issues")
- Note areas where team consistently struggled
- Track where complexity was underestimated
Recurring Review Feedback:
- Identify feedback themes (e.g., "Error handling was flagged in every review")
- Note quality patterns (positive and negative)
- Track areas where team improved over the course of epic
Breakthrough Moments:
- Document key discoveries (e.g., "Story 3 discovered the caching pattern we used for rest of epic")
- Note when team velocity improved dramatically
- Track innovative solutions worth repeating
Velocity Patterns:
- Calculate average completion time per story
- Note velocity trends (e.g., "First 2 stories took 3x longer than estimated")
- Identify which types of stories went faster/slower
Team Collaboration Highlights:
- Note moments of excellent collaboration mentioned in stories
- Track where pair programming or mob programming was effective
- Document effective problem-solving sessions
Store this synthesis - these patterns will drive the retrospective discussion
Calculate previous epic number: {{prev_epic_num}} = {{epic_number}} - 1
Search for previous retrospectives using pattern: {implementation_artifacts}/epic-{{prev_epic_num}}-retro-*.md
<action>Read the previous retrospectives</action>
<action>Extract key elements:</action>
- **Action items committed**: What did the team agree to improve?
- **Lessons learned**: What insights were captured?
- **Process improvements**: What changes were agreed upon?
- **Technical debt flagged**: What debt was documented?
- **Team agreements**: What commitments were made?
- **Preparation tasks**: What was needed for this epic?
<action>Cross-reference with current epic execution:</action>
**Action Item Follow-Through:**
- For each action item from Epic {{prev_epic_num}} retro, check if it was completed
- Cross-check the action_items section in {sprint_status_file} (if present) for Epic {{prev_epic_num}} entries and their current status
- Look for evidence in current epic's story records
- Mark each action item: ✅ Completed, ⏳ In Progress, ❌ Not Addressed
**Lessons Applied:**
- For each lesson from Epic {{prev_epic_num}}, check if team applied it in Epic {{epic_number}}
- Look for evidence in dev notes, review feedback, or outcomes
- Document successes and missed opportunities
**Process Improvements Effectiveness:**
- For each process change agreed to in Epic {{prev_epic_num}}, assess if it helped
- Did the change improve velocity, quality, or team satisfaction?
- Should we keep, modify, or abandon the change?
**Technical Debt Status:**
- For each debt item from Epic {{prev_epic_num}}, check if it was addressed
- Did unaddressed debt cause problems in Epic {{epic_number}}?
- Did the debt grow or shrink?
<action>Prepare "continuity insights" for the retrospective discussion</action>
<action>Identify wins where previous lessons were applied successfully:</action>
- Document specific examples of applied learnings
- Note positive impact on Epic {{epic_number}} outcomes
- Celebrate team growth and improvement
<action>Identify missed opportunities where previous lessons were ignored:</action>
- Document where team repeated previous mistakes
- Note impact of not applying lessons (without blame)
- Explore barriers that prevented application
<output>
Amelia (Developer): "Interesting... in Epic {{prev_epic_num}}'s retro, we committed to {{action_count}} action items."
Alice (Product Owner): "How'd we do on those, Amelia?"
Amelia (Developer): "We completed {{completed_count}}, made progress on {{in_progress_count}}, but didn't address {{not_addressed_count}}."
Charlie (Senior Dev): looking concerned "Which ones didn't we address?"
Amelia (Developer): "We'll discuss that in the retro. Some of them might explain challenges we had this epic."
Elena (Junior Dev): "That's... actually pretty insightful."
Amelia (Developer): "That's why we track this stuff. Pattern recognition helps us improve."
Set {{first_retrospective}} = true
Set {{first_retrospective}} = true
Calculate next epic number: {{next_epic_num}} = {{epic_number}} + 1
Attempt to load next epic using selective loading strategy:
Try sharded first (more specific):
Check if file exists: {planning_artifacts}/epic*/epic-{{next_epic_num}}.md
Load {planning_artifacts}/*epic*/epic-{{next_epic_num}}.md
Set {{next_epic_source}} = "sharded"
Fallback to whole document:
Check if file exists: {planning_artifacts}/epic*.md
Load entire epics document
Extract Epic {{next_epic_num}} section
Set {{next_epic_source}} = "whole"
Analyze next epic for:
- Epic title and objectives
- Planned stories and complexity estimates
- Dependencies on Epic {{epic_number}} work
- New technical requirements or capabilities needed
- Potential risks or unknowns
- Business goals and success criteria
Identify dependencies on completed work:
- What components from Epic {{epic_number}} does Epic {{next_epic_num}} rely on?
- Are all prerequisites complete and stable?
- Any incomplete work that creates blocking dependencies?
Note potential gaps or preparation needed:
- Technical setup required (infrastructure, tools, libraries)
- Knowledge gaps to fill (research, training, spikes)
- Refactoring needed before starting next epic
- Documentation or specifications to create
Check for technical prerequisites:
APIs or integrations that must be ready
Data migrations or schema changes needed
Testing infrastructure requirements
Deployment or environment setup
Amelia (Developer): "Alright, I've reviewed Epic {{next_epic_num}}: '{{next_epic_title}}'"
Alice (Product Owner): "What are we looking at?"
Amelia (Developer): "{{next_epic_num}} stories planned, building on the {{dependency_description}} from Epic {{epic_number}}."
Charlie (Senior Dev): "Dependencies concern me. Did we finish everything we need for that?"
Amelia (Developer): "Good question - that's exactly what we need to explore in this retro."
Set {{next_epic_exists}} = true
Set {{next_epic_exists}} = false
Load agent roster from {agent_roster}
Identify which agents participated in Epic {{epic_number}} based on story records
Ensure key roles present: Product Owner, Developer (facilitating), Testing/QA, Architect
WAIT for {user_name} to respond or indicate readiness
Amelia (Developer) naturally turns to {user_name} to engage them in the discussion
WAIT for {user_name} to respond - this is a KEY USER INTERACTION moment
After {user_name} responds, have 1-2 team members react to or build on what {user_name} shared
Continue facilitating natural dialogue, periodically bringing {user_name} back into the conversation
After covering successes, guide the transition to challenges with care
WAIT for {user_name} to respond and help facilitate the conflict resolution
Use {user_name}'s response to guide the discussion toward systemic understanding rather than blame
Continue the discussion, weaving in patterns discovered from the deep story analysis (Step 3)
WAIT for {user_name} to share their observations
Continue the retrospective discussion, creating moments where:
- Team members ask {user_name} questions directly
- {user_name}'s input shifts the discussion direction
- Disagreements arise naturally and get resolved
- Quieter team members are invited to contribute
- Specific stories are referenced with real examples
- Emotions are authentic (frustration, pride, concern, hope)
WAIT for {user_name} to respond
Use the previous retro follow-through as a learning moment about commitment and accountability
Allow team members to add any final thoughts on the epic review
Ensure {user_name} has opportunity to add their perspective
Skip to Step 9
WAIT for {user_name} to share their assessment
Use {user_name}'s input to guide deeper exploration of preparation needs
WAIT for {user_name} to provide direction on preparation approach
Create space for debate and disagreement about priorities
WAIT for {user_name} to validate or adjust the preparation strategy
Continue working through preparation needs across all dimensions:
- Dependencies on Epic {{epic_number}} work
- Technical setup and infrastructure
- Knowledge gaps and research needs
- Documentation or specification work
- Testing infrastructure
- Refactoring or debt reduction
- External dependencies (APIs, integrations, etc.)
For each preparation area, facilitate team discussion that:
- Identifies specific needs with concrete examples
- Estimates effort realistically based on Epic {{epic_number}} experience
- Assigns ownership to specific agents
- Determines criticality and timing
- Surfaces risks of NOT doing the preparation
- Explores parallel work opportunities
- Brings {user_name} in for key decisions
WAIT for {user_name} final validation of preparation plan
Synthesize themes from Epic {{epic_number}} review discussion into actionable improvements
Create specific action items with:
- Clear description of the action
- Assigned owner (specific agent or role)
- Timeline or deadline
- Success criteria (how we'll know it's done)
- Category (process, technical, documentation, team, etc.)
Ensure action items are SMART:
- Specific: Clear and unambiguous
- Measurable: Can verify completion
- Achievable: Realistic given constraints
- Relevant: Addresses real issues from retro
- Time-bound: Has clear deadline
WAIT for {user_name} to help resolve priority discussions
CRITICAL ANALYSIS - Detect if discoveries require epic updates
Check if any of the following are true based on retrospective discussion:
- Architectural assumptions from planning proven wrong during Epic {{epic_number}}
- Major scope changes or descoping occurred that affects next epic
- Technical approach needs fundamental change for Epic {{next_epic_num}}
- Dependencies discovered that Epic {{next_epic_num}} doesn't account for
- User needs significantly different than originally understood
- Performance/scalability concerns that affect Epic {{next_epic_num}} design
- Security or compliance issues discovered that change approach
- Integration assumptions proven incorrect
- Team capacity or skill gaps more severe than planned
- Technical debt level unsustainable without intervention
WAIT for {user_name} to decide on how to handle the significant changes
Add epic review session to critical path if user agrees
Give each agent with assignments a moment to acknowledge their ownership
Ensure {user_name} approves the complete action plan
Explore testing and quality state through natural conversation
WAIT for {user_name} to describe testing status
WAIT for {user_name} to assess quality readiness
Add testing completion to critical path
Explore deployment and release status
WAIT for {user_name} to provide deployment status
WAIT for {user_name} to clarify deployment timeline
Add deployment milestone to critical path with agreed timeline
Explore stakeholder acceptance
WAIT for {user_name} to describe stakeholder acceptance status
WAIT for {user_name} decision
Add stakeholder acceptance to critical path if user agrees
Explore technical health and stability
WAIT for {user_name} to assess codebase health
WAIT for {user_name} decision
Add stability work to preparation sprint if user agrees
Explore unresolved blockers
WAIT for {user_name} to surface any blockers
Assign blocker resolution to appropriate agent
Add to critical path with priority and deadline
Synthesize the readiness assessment
WAIT for {user_name} to confirm or correct the assessment
WAIT for {user_name} to share final reflections
Prepare to save retrospective summary document
Ensure retrospectives folder exists: {implementation_artifacts}
Create folder if it doesn't exist
Generate comprehensive retrospective summary document including:
- Epic summary and metrics
- Team participants
- Successes and strengths identified
- Challenges and growth areas
- Key insights and learnings
- Previous retro follow-through analysis (if applicable)
- Next epic preview and dependencies
- Action items with owners and timelines
- Preparation tasks for next epic
- Critical path items
- Significant discoveries and epic update recommendations (if any)
- Readiness assessment
- Commitments and next steps
Format retrospective document as readable markdown with clear sections
Set filename: {implementation_artifacts}/epic-{{epic_number}}-retro-{date}.md
Save retrospective document
Update {sprint_status_file} to mark retrospective as completed
Load the FULL file: {sprint_status_file}
Find development_status key "epic-{{epic_number}}-retrospective"
Verify current status (typically "optional" or "pending")
Update development_status["epic-{{epic_number}}-retrospective"] = "done"
Append each Epic {{epic_number}} action item to the action_items section, creating the section after development_status if missing. One entry per item:
action_items:
- epic: {{epic_number}}
action: "{{action_description}}"
owner: "{{owner}}"
status: open
Quote action and owner values so punctuation (e.g., "#") cannot break YAML parsing
Update Epic {{prev_epic_num}} action_items entries based on Step 4 follow-through: ✅ Completed → done, ⏳ In Progress → in-progress, ❌ Not Addressed → keep existing status (do not modify)
Update last_updated field to current date
Save file, preserving ALL comments and structure including STATUS DEFINITIONS
Run: `python3 {project-root}/_bmad/scripts/resolve_customization.py --skill {skill-root} --key workflow.on_complete` — if the resolved value is non-empty, follow it as the final terminal instruction before exiting.
By