bmad-retrospective

Review completed epics against git diffs, commits, and sprint status to produce sourced retrospective findings and verdicts.

Updated Sep 4, 2026
One-click install
npx skills add https://github.com/Joao-Victor-Medeiros/save-sc --skill bmad-retrospective-joao-victor-medeiros
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: bmad-retrospective
Source: https://github.com/Joao-Victor-Medeiros/save-sc/tree/main/.agents/skills/bmad-retrospective
Command: npx skills add https://github.com/Joao-Victor-Medeiros/save-sc --skill bmad-retrospective-joao-victor-medeiros

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill requires ruamel.yaml, and includes scripts (resource) and references (resource) components.

What problem does it solve? After an epic finishes, no single coding session ever saw the whole change, so cross-story defects like god-class growth, duplication, and spec drift go unnoticed. This Skill reads the evidence an epic left behind — spec, story files, diffs, commits, sprint status — and produces a retrospective where every finding carries a source reference. ## Core Features & Use Cases - Evidence-based analysis: Derives per-story commit attribution and per-file change volume from git ranges, then builds aggregate views (architecture delta, duplication map, pattern divergence, spec reconciliation) across the full epic diff. - Acceptance verdict: Judges the epic against declared or profiled acceptance criteria and renders accepted, accepted-with-open-items, or rejected, with unfinished stories forcing a machine verdict of rejected. - Sprint-status integration: Updates sprint-status.yaml atomically via a comment-preserving script, marking the retro done and appending owned action items with stable IDs. - Use Case: After an unattended multi-story epic run, ask for a retrospective to get a document listing sourced findings, routed action items, follow-through on the previous epic's action items, and an acceptance decision an orchestrator can gate on. ## Quick Start Run a retrospective on epic 3 by saying "lets retro the epic 3" after its stories are marked done.

Frequently Asked Questions about bmad-retrospective

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I run a retrospective on a completed epic?▼

Say "run a retrospective" or "lets retro the epic [number]" after the epic's stories are done. The skill detects the epic from sprint-status.yaml, gathers the diff range and commits, analyzes aggregate views, and writes a retrospective document with findings and a verdict.

How does the retrospective detect which epic to review?▼

It runs the bundled sprint_status.py detect-epic script against sprint-status.yaml, returning the highest epic with a done story, or scoping to an epic number you pass explicitly. In stories mode it reads a spec folder with SPEC.md and stories.yaml instead.

Can I run the epic retrospective headless for automation?▼

Yes, pass -H or --headless with an explicit epic number for unattended runs. Headless mode skips confirmations and team discussion, records every assumption in the document, and still forces a rejected verdict when stories remain unfinished.

What happens if an epic has unfinished stories during the retrospective?▼

The detect-epic script returns a pending_stories list scoped to that epic. Interactively you are asked whether to proceed; either way the machine acceptance verdict is rejected, and only a human decision can override it.

Does the retrospective modify sprint-status.yaml safely?▼

Yes, the sprint_status.py update command round-trips through a comment-preserving YAML parser, writes atomically via temp file and rename, and validates the result, restoring the original bytes if validation fails. Hand-editing the file is explicitly forbidden.

What are the limitations of the retrospective findings?▼

Every finding must carry a source reference to a file, line, commit, or log; anything that cannot be tied to evidence is dropped. Missing session logs or undeclared acceptance criteria narrow the analysis scope, and the narrowing is recorded in the document.