bmad-retrospective

Retrospective

Review a completed epic by reading the evidence it left — the epic spec, story files, the full diff, per-story commits, sprint status, and session logs when they exist. An unattended epic run leaves a record; this skill reads that record, surfaces the defects no single story could show, and judges the epic against the criteria it set for itself.

Every finding you report carries a source reference (file, line, commit, or log). A claim you cannot point at — an invented root cause, a pattern the diff does not actually show — is not a finding. Drop it.

Resolution rules

• Bare paths and {skill-root} (e.g. references/aggregate-views.md, scripts/sprint_status.py) resolve from this skill's installed directory.
• {project-root} → the project working directory.
• {skill-name} → the skill directory's basename.

Modes

Interactive by default. With -H/--headless: skip every confirmation, take the epic from the invocation (falling back to detection only if none was supplied), never open the team discussion, render the verdict on the evidence alone, and record each assumption made without the user (which epic was selected, the machine verdict, each proposed item) into the retrospective document's Assumptions section so the audit trail survives. The Phase 4 acceptance fail-safe still applies in headless runs.

For automation, -H <epic> — an explicit epic in headless mode — is the stable orchestrator-facing interface. Pass the same number to detect-epic --epic <N> so the unfinished-story gate is script-backed (see Inputs). Epic auto-detection is a human convenience, not an automation contract: unflagged detect-epic returns the highest epic with any done story, and stories-mode projects have no sprint-status.yaml to detect from.

On Activation

Run these in order before the retrospective begins:

1. Resolve the workflow block. Run uv run --no-cache {project-root}/_bmad/scripts/resolve_customization.py --skill {skill-root} --key workflow. If it fails, resolve {workflow.*} yourself by reading {skill-root}/customize.toml, then {project-root}/_bmad/custom/{skill-name}.toml, then .user.toml in that order, merging base → team → user (scalars override, keyed arrays-of-tables merge by code/id, other arrays append).
2. Run prepend steps — execute each entry in {workflow.activation_steps_prepend} in order.
3. Load persistent facts — treat every {workflow.persistent_facts} entry as standing context. file: entries are paths/globs under {project-root} whose contents load as facts; all others are literal facts.
4. Load config from {project-root}/_bmad/bmm/config.yaml: project_name, user_name, communication_language, document_output_language, user_skill_level, planning_artifacts, implementation_artifacts, and date (system datetime), plus output_folder from {project-root}/_bmad/core/config.yaml. Speak all output in {communication_language}; write all documents in {document_output_language}. Never state time estimates — AI has changed development speed, so hour/day/week predictions are noise.
5. Greet and orient (interactive only). Greet {user_name}, name the epic you are about to retro, and optionally invite their going-in concerns ("anything you want weighted — a story that felt rushed, a risky interaction between two stories?"). Use any answer to focus the Phase 1–2 analysis; it directs attention but never becomes a finding without a source.
6. Run append steps — execute each entry in {workflow.activation_steps_append} in order.