bmad-retrospective

Reviews completed epics against sourced evidence and renders an acceptance verdict.

Updated Sep 3, 2026
One-click install
npx skills add https://github.com/watchthelight/shatterfish --skill bmad-retrospective-watchthelight
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: bmad-retrospective
Source: https://github.com/watchthelight/shatterfish/tree/main/.claude/skills/bmad-retrospective
Command: npx skills add https://github.com/watchthelight/shatterfish --skill bmad-retrospective-watchthelight

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 can see the defects the whole change introduced — god classes grown across nine stories, duplicated logic, spec drift. This Skill reads the evidence an epic left behind (spec, story files, full diff, commits, sprint status, session logs) and produces a sourced findings report plus an honest acceptance verdict. ## Core Features & Use Cases - Evidence-based findings: Every reported finding carries a source reference (file, line, commit, or log); claims without a source are dropped. - Aggregate diff analysis: Derives architecture deltas, duplication maps, god-class growth, pattern divergence, and spec-to-implementation reconciliation across the full epic diff range via deterministic scripts. - Acceptance verdict with gates: Renders accepted, accepted-with-open-items, or rejected against declared or profiled criteria; unfinished stories force a machine verdict of rejected. - Sprint-status integration: Updates sprint-status.yaml atomically with comment preservation, appending owned action items and marking the retro key done, with rollback on validation failure. - Use Case: After an unattended multi-story epic run, ask for a retrospective to get a document listing what was built, which cross-story defects the diff reveals, whether last epic's action items landed, and whether the epic met its own acceptance criteria. ## Quick Start Ask the assistant to run a retrospective on the most recently completed epic, or pass an epic number explicitly for a headless run.

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 an epic number or let it detect the highest epic with a done story from sprint-status.yaml. It gathers the spec, story files, and diff range, then produces findings and an acceptance verdict in a retrospective document.

How does the retrospective detect cross-story defects?

It derives aggregate views over the full epic diff range: architecture delta, duplication map, god-class growth, pattern divergence, and spec-to-implementation reconciliation. A bundled git_evidence.py script measures per-file churn and per-story commit attribution deterministically.

Can the retrospective run headless without user interaction?

Yes, pass -H or --headless with an explicit epic number. It skips confirmations, renders the verdict from evidence alone, and records every assumption made without the user in the document's Assumptions section.

What happens if an epic has unfinished stories?

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

Does the retrospective modify sprint-status.yaml safely?

Updates go through a bundled script that round-trips YAML preserving comments, 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 verdict?

If no acceptance criteria were declared, the verdict is profiled from the diff and flagged as such. When sprint-status.yaml is unreadable, the completeness check cannot run and the document records that gap rather than guessing.