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.