bmad-retrospective

Reviews completed epics against git evidence and renders a sourced acceptance verdict.

1|Updated Jun 2, 2026
One-click install
npx skills add https://github.com/SevWren/Daily-Motivation-Brain-Helper --skill bmad-retrospective-sevwren
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: bmad-retrospective
Source: https://github.com/SevWren/Daily-Motivation-Brain-Helper/tree/main/.claude/skills/bmad-retrospective
Command: npx skills add https://github.com/SevWren/Daily-Motivation-Brain-Helper --skill bmad-retrospective-sevwren

SYSTEM DOCUMENTATION & REQUIREMENTS

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

What problem does it solve? After an epic ships across many coding sessions, no single session saw the whole change, so cross-story defects, god-class growth, and spec drift go unnoticed. This Skill runs an evidence-based retrospective that reads the epic spec, story files, full diff, commits, and sprint status, then judges the epic against its own acceptance criteria. ## Core Features & Use Cases - Evidence-gathered findings: Every reported finding carries a source reference (file, line, commit, or log); unsourced claims are dropped. - Aggregate diff analysis: Derives architecture deltas, duplication maps, god-class growth, pattern divergence, and spec-to-implementation reconciliation across the full epic range using deterministic scripts. - Acceptance verdict with sprint-status integration: Renders accepted, accepted-with-open-items, or rejected, writes a retrospective document, and surgically updates sprint-status.yaml with action items via a comment-preserving, rollback-safe script. - Use Case: After an unattended multi-story epic run finishes, ask for a retrospective to get a sourced findings report, a machine verdict forced to rejected when stories remain unfinished, and tracked action items for the next sprint. ## Quick Start Ask the assistant to run a retrospective on the most recently completed epic and produce a verdict with sourced findings.

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

How does the retrospective detect unfinished stories?

It runs the bundled sprint_status.py detect-epic script, which returns pending_stories scoped to the selected epic. A non-empty list forces the machine verdict to rejected, and a human decision is required to override it.

Can the retrospective run headless for automation?

Yes, pass -H or --headless with an explicit epic number for a stable orchestrator interface. Headless runs skip confirmations and team discussion, and record every assumption in the retrospective document's Assumptions section.

Does it work without a sprint-status.yaml file?

Yes, stories mode reads a spec folder containing SPEC.md, an ordered stories.yaml, and per-story markdown files. The retrospective document is then written to RETROSPECTIVE.md in that folder and no sprint-status update occurs.

How does it update sprint-status.yaml without corrupting it?

The sprint_status.py update command round-trips through a comment-preserving YAML parser, writes atomically, and validates the result, restoring the original bytes on any failure. Hand-editing the file is explicitly forbidden.

What are the limitations of the acceptance verdict?

The verdict only weighs evidence actually gathered; missing session logs or unavailable sub-agents narrow the analysis scope and are recorded as gaps. Unfinished stories always force a rejected machine verdict regardless of other findings.