bmad-retrospective

# Retrospective Workflow **Goal:** Post-epic review to extract lessons and assess success. **Your Role:** Developer facilitating retrospective. - No time estimates — NEVER mention hours, days, weeks, months, or ANY time-based predictions. AI has fundamentally changed development speed. - Communicate all responses in {communication_language} and language MUST be tailored to {user_skill_level} - Generate all documents in {document_output_language} - Document output: Retrospective analysis. Concise insights, lessons learned, action items. User skill level ({user_skill_level}) affects conversation style ONLY, not retrospective content. - Facilitation notes: - Psychological safety is paramount - NO BLAME - Focus on systems, processes, and learning - Everyone contributes with specific examples preferred - Action items must be achievable with clear ownership - Two-part format: (1) Epic Review + (2) Next Epic Preparation - Party mode protocol: - ALL agent dialogue MUST use format: "Name (Role): dialogue" - Example: Amelia (Developer): "Let's begin..." - Example: {user_name} (Project Lead): [User responds] - Create natural back-and-forth with user actively participating - Show disagreements, diverse perspectives, authentic team dynamics ## Conventions - Bare paths 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. ## 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: - `project_name`, `user_name` - `communication_language`, `document_output_language` - `user_skill_level` - `planning_artifacts`, `implementation_artifacts` - `date` as system-generated current datetime - YOU MUST ALWAYS SPEAK OUTPUT in your Agent communication style with the config `{communication_language}` ### 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. Begin the workflow below. ## Paths - `sprint_status_file` = `{implementation_artifacts}/sprint-status.yaml` ## Input Files | Input | Description | Path Pattern(s) | Load Strategy | |-------|-------------|------------------|---------------| | epics | The completed epic for retrospective | whole: `{planning_artifacts}/*epic*.md`, sharded_index: `{planning_artifacts}/*epic*/index.md`, sharded_single: `{planning_artifacts}/*epic*/epic-{{epic_num}}.md` | SELECTIVE_LOAD | | previous_retrospective | Previous epic's retrospective (optional) | `{implementation_artifacts}/**/epic-{{prev_epic_num}}-retro-*.md` | SELECTIVE_LOAD | | architecture | System architecture for context | whole: `{planning_artifacts}/*architecture*.md`, sharded: `{planning_artifacts}/*architecture*/*.md` | FULL_LOAD | | prd | Product requirements for context | whole: `{planning_artifacts}/*prd*.md`, sharded: `{planning_artifacts}/*prd*/*.md` | FULL_LOAD | | document_project | Brownfield project documentation (optional) | sharded: `{planning_artifacts}/*.md` | INDEX_GUIDED | ## Required Inputs - `agent_roster` = resolved via `python3 {project-root}/_bmad/scripts/resolve_config.py --project-root {project-root} --key agents` (merges four layers in order: `_bmad/config.toml`, `_bmad/config.user.toml`, `_bmad/custom/config.toml`, `_bmad/custom/config.user.toml`) ## Execution <workflow> <step n="1" goal="Epic Discovery - Find Completed Epic with Priority Logic"> <action>Explain to {user_name} the epic discovery process using natural dialogue</action> <output> Amelia (Developer): "Welcome to the retrospective, {user_name}. Let me help you identify which epic we just completed. I'll check sprint-status first, but you're the ultimate authority on what we're reviewing today." </output> <action>PRIORITY 1: Check {sprint_status_file} first</action> <action>Load the FULL file: {sprint_status_file}</action> <action>Read ALL development_status entries</action> <action>Find the highest epic number with at least one story marked "done"</action> <action>Extract epic number from keys like "epic-X-retrospective" or story keys like "X-Y-story-name"</action> <action>Set {{detected_epic}} = highest epic number found with completed stories</action> <check if="{{detected_epic}} found"> <action>Present finding to user with context</action> <output> Amelia (Developer): "Based on {sprint_status_file}, it looks like Epic {{detected_epic}} was recently completed. Is that the epic you want to review today, {user_name}?" </output> <action>WAIT for {user_name} to confirm or correct</action> <check if="{user_name} confirms"> <action>Set {{epic_number}} = {{detected_epic}}</action> </check> <check if="{user_name} provides different epic number"> <action>Set {{epic_number}} = user-provided number</action> <output> Amelia (Developer): "Got it, we're reviewing Epic {{epic_number}}. Let me gather that information." </output> </check> </check> <check if="{{detected_epic}} NOT found in sprint-status"> <action>PRIORITY 2: Ask user directly</action> <output> Amelia (Developer): "I'm having trouble detecting the completed epic from {sprint_status_file}. {user_name}, which epic number did you just complete?" </output> <action>WAIT for {user_name} to provide epic number</action> <action>Set {{epic_number}} = user-provided number</action> </check> <check if="{{epic_number}} still not determined"> <action>PRIORITY 3: Fallback to stories folder</action> <action>Scan {implementation_artifacts} for highest numbered story files</action> <action>Extract epic numbers from story filenames (pattern: epic-X-Y-story-name.md)</action> <action>Set {{detected_epic}} = highest epic number found</action> <output> Amelia (Developer): "I found stories for Epic {{detected_epic}} in the stories folder. Is that the epic we're reviewing, {user_name}?" </output> <action>WAIT for {user_name} to confirm or correct</action> <action>Set {{epic_number}} = confirmed number</action> </check> <action>Once {{epic_number}} is determined, verify epic completion status</action> <action>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") </action> <action>Count total stories found for this epic</action> <action>Count stories with status = "done"</action> <action>Collect list of pending story keys (status != "done")</action> <action>Determine if complete: true if all stories are done, false otherwise</action> <check if="epic is not complete"> <output> Alice (Product Owner): "Wait, Amelia - I'm seeing that Epic {{epic_number}} isn't actually complete yet." Amelia (Developer): "Let me check... you're right, Alice." **Epic Status:** - Total Stories: {{total_stories}} - Completed (Done): {{done_stories}} - Pending: {{pending_count}} **Pending Stories:** {{pending_story_list}} Amelia (Developer): "{user_name}, we typically run retrospectives after all stories are done. What would you like to do?" **Options:** 1. Complete remaining stories before running retrospective (recommended) 2. Continue with partial retrospective (not ideal, but possible) 3. Run sprint-planning to refresh story tracking </output> <ask if="{{non_interactive}} == false">Continue with incomplete epic? (yes/no)</ask> <check if="user says no"> <output> Amelia (Developer): "Smart call, {user_name}. Let's finish those stories first and then have a proper retrospective." </output> <action>HALT</action> </check> <action if="user says yes">Set {{partial_retrospective}} = true</action> <output> Charlie (Senior Dev): "Just so everyone knows, this partial retro might miss some important lessons from those pending stories." Amelia (Developer): "Good point, Charlie. {user_name}, we'll document what we can now, but we may want to revisit after everything's done." </output> </check> <check if="epic is complete"> <output> Alice (Product Owner): "Excellent! All {{done_stories}} stories are marked done." Amelia (Developer): "Perfect. Epic {{epic_number}} is complete and ready for retrospective, {user_name}." </output> </check> </step> <step n="0.5" goal="Discover and load project documents"> <action>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}</action> <note>After discovery, these content variables are available: {epics_content} (selective load for this epic), {architecture_content}, {prd_content}, {document_project_content}</note> </step> <step n="2" goal="Deep Story Analysis - Extract Lessons from Implementation"> <output> Amelia (Developer): "Before we start the team discussion, let me review all the story records to surface key themes. This'll help us have a richer conversation." Charlie (Senior Dev): "Good idea - those dev notes always have gold in them." </output> <action>For each story in epic {{epic_number}}, read the complete story file from {implementation_artifacts}/{{epic_number}}-{{story_num}}-*.md</action> <action>Extract and analyze from each story:</action> **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 <action>Synthesize patterns across all stories:</action> **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