bmad-retrospective

Review a completed epic against its specs, diffs, and commits to produce a sourced retrospective with an acceptance verdict.

1|Updated Sep 18, 2026
One-click install
npx skills add https://github.com/PastaSus/egg-defender --skill bmad-retrospective-pastasus
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: bmad-retrospective
Source: https://github.com/PastaSus/egg-defender/tree/main/.agents/skills/bmad-retrospective
Command: npx skills add https://github.com/PastaSus/egg-defender --skill bmad-retrospective-pastasus

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, ending in an honest acceptance verdict. ## Core Features & Use Cases - Evidence-based analysis: Gathers the epic spec, story files, diff range, and per-story commits via deterministic scripts, then derives aggregate views (architecture delta, duplication map, god-class growth, spec reconciliation) that no single diff hunk reveals. - Acceptance verdict with fail-safes: Judges the epic against declared or profiled acceptance criteria as accepted, accepted-with-open-items, or rejected; unfinished stories force a machine verdict of rejected unless a human overrides. - Sprint-status integration: Updates sprint-status.yaml atomically through a comment-preserving script that marks the retro done, appends owned action items, and validates every write with rollback on failure. - 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 a verdict an orchestrator can gate the next epic on. ## Quick Start Ask the assistant to run a retrospective on the epic you just finished, for example by saying "run a retrospective on epic 3".

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?

Invoke the skill with the epic number, for example "run a retrospective on epic 3". It detects the epic from sprint-status.yaml when none is supplied, gathers the spec, stories, diff range, and commits, then produces a sourced findings document with an acceptance verdict.

How does the retrospective detect which epic to review?

It runs the bundled sprint_status.py detect-epic command against sprint-status.yaml, returning the highest epic with a done story, or the epic 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 the stable orchestrator interface. Headless runs skip confirmations and team discussion, record every assumption in the document, and still force a rejected verdict when stories remain unfinished.

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

The detect-epic script reports pending_stories scoped to that epic, and any non-empty list forces the machine acceptance verdict to rejected. Interactive runs let a human override after seeing the list; headless runs record the rejection without inventing a confirmation.

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 on any failure. 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 pointed at is dropped. Missing evidence such as absent session logs narrows the analysis scope, and the document records what was never checked.