bmad-retrospective

Review a completed epic against its evidence and produce a sourced retrospective with verdict.

Updated Mar 1, 2026
One-click install
npx skills add https://github.com/Hexalith/Hexalith.Parties --skill bmad-retrospective-hexalith
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: bmad-retrospective
Source: https://github.com/Hexalith/Hexalith.Parties/tree/main/.agents/skills/bmad-retrospective
Command: npx skills add https://github.com/Hexalith/Hexalith.Parties --skill bmad-retrospective-hexalith

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, teams lack a structured way to judge what actually shipped: defects that no single story review could catch, unfinished stories, and unverified claims about quality. 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: Gathers the epic spec, story files, diff range, per-story commits, and sprint status, then derives aggregate views (architecture delta, duplication map, god-class growth, spec-to-implementation reconciliation) via deterministic scripts. - 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 safely through a comment-preserving, atomic-write script that appends action items and marks the retrospective done. - Use Case: After an unattended multi-story epic run, ask for a retrospective to get a document listing sourced findings, routed action items with owners, follow-through on the previous epic's action items, and an honest acceptance verdict. ## Quick Start Ask the assistant to run a retrospective on the epic you just completed, 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 by saying run a retrospective or lets retro the epic, optionally passing the epic number. It detects the epic from sprint-status.yaml or a spec folder, gathers the diff and story evidence, and writes a retrospective document with findings and a verdict.

How does the epic retrospective decide accepted versus rejected?▼

The verdict compares the final state against the epic's declared acceptance criteria, or criteria profiled from the diff when none were declared. Any unfinished story in pending_stories forces a machine verdict of rejected, though a human decision can override interactively.

Can I run the retrospective headless for automation?▼

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

Does the retrospective 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 instead of sprint status. The retrospective is then written to RETROSPECTIVE.md in that folder and no sprint-status file is created or modified.

Why does the retrospective update script fail on sprint-status.yaml?▼

The update script validates all inputs before writing and restores the original file on any failure, reporting ok false with restored true. Common causes are an invalid date format, a verdict outside the accepted vocabulary, or a set-action-status selector matching zero or multiple items.