Retro

Retrospective Skill

Generate honest, structured retrospectives for any Claude Code project. Retrospectives are the primary communication channel between engineering execution and product/stakeholder visibility.

Core Principles

1. Adapt to the project — A 3-commit side project and a 50-phase enterprise migration both get useful retrospectives.
2. Honest by default — Surface deviations, bugs, wrong assumptions, and scope surprises prominently. Never omit negative findings.
3. Composable providers — Read from jira, git, GitHub, and the user. Never write to .project/ or modify git history.
4. Idempotent — Running /retro 1 twice overwrites the previous output. No duplicates.
5. Manual fills the gaps — For anything automation can't derive, ask the user.

Commands

Execution Flow

1. Load or Initialize Config

Read .claude/retrospective.config.json. If missing, run first-run initialization (see references/config.md for schema and first-run behavior).

1.5. Detect Jira Workflow

Probe for .jira/STATE.md at the project root. If absent, skip this step.

If found, the repo uses the jira plugin for sprint state. This skill does not read .jira/sprints/* files — that coupling lives inside /jira:retro, which knows how to interpret CONTEXT.md (locked decisions D-XX), VERIFICATION.md (goal-backward outcomes), and per-wave PLAN files.

Surface this to the user via AskUserQuestion before proceeding:

Copy code
Detected .jira/ — this repo uses the jira plugin for sprint state.

For per-sprint retros, /jira:retro <sprint-slug> is the right tool —
it reads BRIEF.md, CONTEXT.md, every *-PLAN.md, EXECUTION.md, and
VERIFICATION.md for that sprint.

/retro here covers cross-sprint rollups via git + github only — it
intentionally does NOT open jira's per-sprint files.

Options:

• Switch to /jira:retro — exit this skill; tell the user to invoke /jira:retro <slug> (or /jira:retro --since <date> for cross-sprint rollup inside the plugin).
• Continue here for cross-sprint rollup — proceed. Disable the gsd provider for this run (it would misfire on legacy .planning/ patterns the jira repo doesn't use). Use only git, github, and manual. Note in the final retrospective output: "Generated by /retro with jira detection — per-sprint detail intentionally not included; see /jira:retro for that."

2. Identify the Phase

• If phase number/name provided (e.g., /retro 3), use it.
• Otherwise, determine most recently completed phase from enabled providers:
  • GSD: read .planning/STATE.md for current phase (skipped if jira-detected continue path was taken in step 1.5)
  • Git: find latest tag or merged branch
  • GitHub: find most recently closed milestone via gh
  • Manual: ask the user

3. Gather Phase Data

Query all enabled providers. For provider details, probe logic, and precedence rules, see references/providers.md.

Collect across providers:

• Objective, scope, success criteria
• What happened (summaries, commits, PRs)
• Decisions made (decision logs, PR descriptions, commit messages)
• Issues and deviations (reverts, fixups, issue comments)
• Quantitative metrics (git stats, PR/issue counts)
• Artifacts produced (file lists, diff stats)

Provider precedence (merge, never discard): GSD → GitHub → Git → Manual

4. Populate the Template

Use the project's template from config, or the built-in default at _templates/PHASE-RETRO-TEMPLATE.md. Fill all 10 sections:

Tone: Surface the bad and the ugly prominently. Sugarcoating defeats the purpose.

5. Completeness Check

Before writing, self-audit the retrospective. For each of the 10 sections:

If any section is empty: Go back to Step 3 and ask the user via manual provider. Do not write a retrospective with blank sections.

Manual question minimums by data richness:

• If GSD or GitHub provide structured data: minimum 3 manual questions.
• If only git and manual are active: minimum 5 manual questions (git provides metrics but not subjective context).
• If only manual is active: minimum 7 manual questions (you are the sole data source besides the user).

Go back and ask about surprises, failures, forward risks, edge cases, and decisions at minimum.

6. Write the Retrospective

Save to <retrospective_dir>/phase-<N>-<slug>.md (default: .jira/sprints/<active-slug>/ if jira-managed, otherwise .project/retros/). Overwrite if exists.

Slug derivation: Phase name lowercased, spaces replaced with hyphens, non-alphanumeric characters (except hyphens) removed, truncated to 50 characters. If no phase name exists, use phase number only: phase-<N>.md.

7. Update Cumulative Summary

If summary_tracker.auto_update is true, update <retrospective_dir>/SUMMARY.md:

• Phase column in project-level metrics table
• Phase completion status (status, confidence, key outcome)
• Cross-phase learnings (recurring themes, compounding risks)
• Cumulative risk register
• Project-level decisions

If SUMMARY.md doesn't exist, create from built-in default at _templates/SUMMARY-TEMPLATE.md.

8. Generate Stakeholder Report

If stakeholder_report.auto_generate is true, generate <retrospective_dir>/phase-<N>-<slug>-stakeholder.md from _templates/STAKEHOLDER-REPORT-TEMPLATE.md:

• Plain language, no jargon
• Lead with outcomes and numbers
• Risks and blockers up front
• Next phase preview with readiness assessment

Hook Enforcement

The skill ships with hooks/retro-trigger.sh — a real Claude Code PostToolUse hook, not just instructions.

What It Detects

Behavior by Mode

• auto: Prints [retro] Phase N complete. Auto-generating retrospective... to stderr (exit 2). The agent sees this as a hook message and should run /retro.
• prompt: Prints the prompt message and writes pending_retro to config. User decides when to run /retro.
• manual: Hook exits 0 silently. No-op.

Registration

The hook must be registered in the project's .claude/settings.json:

jsonCopy code
{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write|Bash",
        "hooks": [
          {
            "type": "command",
            "command": "~/.claude/hooks/retro-trigger.sh",
            "timeout": 10
          }
        ]
      }
    ],
    "SessionStart": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "~/.claude/hooks/retro-reminder.sh",
            "timeout": 5
          }
        ]
      }
    ]
  }
}

On /retro init, register both hooks automatically if the project's .claude/settings.json doesn't already have them. Merge into existing hook arrays — do not overwrite existing hooks for the same trigger.

Two hooks, two jobs:

• retro-trigger.sh (PostToolUse) — detects phase completion in real time
• retro-reminder.sh (SessionStart) — reminds about deferred retros on session start

See references/config.md for pending_retro schema.

Reference Files

• references/config.md — Full config schema, field reference, first-run initialization logic
• references/providers.md — Data provider details, probe logic, what each reads, precedence rules
• _templates/PHASE-RETRO-TEMPLATE.md — Default phase retrospective template
• _templates/STAKEHOLDER-REPORT-TEMPLATE.md — Default stakeholder report template
• _templates/SUMMARY-TEMPLATE.md — Default cumulative summary template