bmad-retrospective

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

Updated Jul 2, 2026
One-click install
npx skills add https://github.com/tuanpa-nhg-eng/nhg-ipms --skill bmad-retrospective-tuanpa-nhg-eng
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: bmad-retrospective
Source: https://github.com/tuanpa-nhg-eng/nhg-ipms/tree/main/.claude/skills/bmad-retrospective
Command: npx skills add https://github.com/tuanpa-nhg-eng/nhg-ipms --skill bmad-retrospective-tuanpa-nhg-eng

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, no single coding session saw the whole change, so cross-story defects, god-class growth, and spec drift go unnoticed. This Skill reads the evidence an epic left behind — specs, story files, diffs, commits, sprint status — and produces a sourced retrospective with 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 like architecture delta, duplication maps, and spec-to-implementation reconciliation. - Acceptance verdict: Judges the epic against declared or profiled acceptance criteria as accepted, accepted-with-open-items, or rejected, with unfinished stories forcing a machine verdict of rejected. - Sprint-status integration: Updates sprint-status.yaml atomically with comment preservation, appending owned action items and validating every write with rollback on failure. - Use Case: After an unattended multi-story epic run finishes, ask for a retrospective to get a document listing every finding with its file, line, or commit source, plus routed action items and a verdict an orchestrator can gate the next epic on. ## Quick Start Run a retrospective on epic 3 and tell me whether it passed its acceptance criteria.

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 detect the highest epic with a done story from sprint-status.yaml. It gathers the spec, stories, and diff evidence, then produces a findings document and an acceptance verdict.

How does the retrospective detect unfinished stories before reviewing?

The sprint_status.py detect-epic command returns pending_stories scoped to the selected epic. A non-empty list forces the machine verdict to rejected, and story_count of zero flags a likely mistyped epic number.

Can the retrospective run headless in an automated pipeline?

Yes, pass -H with an explicit epic number for the stable orchestrator interface. Headless runs skip confirmations and team discussion, record every assumption in the document, and never write action-item status transitions.

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 artifacts. It writes RETROSPECTIVE.md in that folder and never creates or edits sprint-status files.

Why does the verdict live in the document frontmatter instead of sprint-status.yaml?

The sprint-status retro key only records that the retrospective ran, so existing lifecycle consumers keep working. Orchestrators gating the next epic must read the verdict key in the retrospective document's YAML frontmatter.

What happens if the sprint-status update fails mid-write?

The script writes atomically via temp file and rename, then re-parses and validates the result. Any validation failure restores the original bytes and reports restored: true, so the file is never left partially written.