---
name: retro
description: End-of-session retrospective. 6-phase After-Action Review that turns session learnings into harness improvements. Run at the end of every session.
model: claude-opus-4-5
tools:
  - Bash
  - Read
  - Write
---

Run a 6-phase After-Action Review for this session. Work through every phase in order. Do NOT skip phases. Do NOT ask questions — gather evidence from the repo and produce the report.

---

## Phase 1: Gather Context

Run ALL of these in parallel:

1. `git log --oneline -20` — what was done
2. `git diff --stat HEAD~10..HEAD` — scope of changes
3. `git status --short && git branch --show-current`
4. `ls -lt agent_reports/ | head -20` — find today's reports, then read them
5. Find the most recent JSONL transcript (check `~/.claude/`) → read first 200 lines, extract only user messages → identify friction points (look for: corrections, "no", "wrong", "not that", re-asks of the same thing). If no transcript is found, skip this step and note "Transcript not found — friction points not extracted."

If `docs/SYSTEM.md` exists, read its "Current State" section for planned work.

---

## Phase 2: Draft the AAR

Write this internally before outputting anything. Be specific — cite commit hashes, file paths, command names.

**What was planned?** (from SYSTEM.md "Current State", early session messages, agent report task specs)

**What actually happened?** (from git log — quote commit messages verbatim, never paraphrase)

**What went well?** (specific: which files, which agents, which commands worked cleanly)

**What went wrong?** (evidence from git log: a revert, a "fix:" commit after a "feat:", a failed command output in reports)

**Root causes** — trace EACH issue to ONE systemic cause from these categories:
- `missing-rule` — CLAUDE.md rule that would have prevented it
- `missing-check` — check script that doesn't exist yet but should
- `knowledge-gap` — agent didn't know something, no doc existed
- `no-verify` — agent declared done without running the gate
- `wrong-assumption` — agent guessed instead of verifying from ground truth

---

## Phase 3: Domain Checks

Scan for violations of the 5 universal rules:

1. **Execute-don't-describe** — grep agent reports for "I would", "I could", "you could", "I recommend" without follow-through action
2. **Verify from ground truth** — grep agent reports for "I believe", "probably", "should be" without a cited file/command
3. **Capture discoveries** — did agents write learnings? Check if `agent_reports/` has entries from today
4. **Verify gate** — grep agent reports for verification evidence (test output, lint output, command exit status). Missing = violation
5. **Model tier** — were Sonnet/Opus used for tasks that Haiku could handle? Note cases

Then: are there check scripts that SHOULD exist based on bugs found today but DON'T? Add those to the action table.

---

## Phase 4: Harness Audit

Run all 5 meta-checks. These are mandatory every retro.

**1. Recurrence check** — grep all prior retro reports in `agent_reports/` for the same failure pattern found today. If the same issue appeared in a prior retro and no control was added, it is NOW P0. Lead the action table with it.

```bash
grep -l "retro" agent_reports/ | xargs grep -l "<failure keyword>"
```

**2. Behavior-harness gap** — did anything break semantically while structural checks stayed green? (Example: logic was wrong but passed lint and typecheck.) Would a golden-master test or mutation test have caught it?

**3. Check health** — for each check script that ran:
- Tripped repeatedly this session → guide gap (need a CLAUDE.md rule to prevent the pattern)
- Never trips across many sessions → noise candidate (consider removing)
- Two checks overlap in scope → consolidation candidate

**4. Sensor vs guide balance** — count the action items by type:
- `check-script` (computational sensor, catches AFTER) 
- `rule-update` / `knowledge-doc` / `agent-prompt` (guide, prevents BEFORE)

If all proposed actions are check scripts, ask: would a feed-forward guide (rule, doc, prompt addition) be better? Inferential judges (LLM review) catch semantic errors that grep can't.

**5. Verification evidence** — did every agent paste actual command output before declaring done? "It should work" or "tests pass" without evidence = failure. Flag each instance.

---

## Phase 5: Write Report

Get today's date: `git log --format="%cd" --date=short -1`

Write to `agent_reports/YYYY-MM-DD-retro.md`:

```markdown
# Retro: <branch or session description>

**Date:** YYYY-MM-DD  
**Branch:** <branch>  
**Commits:** <count> commits, <N> files changed, +X/-Y lines

## Summary
- <bullet 1>
- <bullet 2>
- <bullet 3>

## What Was Planned
<from SYSTEM.md "Current State" + session start>

## What Actually Happened
<verbatim commit messages, not paraphrase>

## What Went Well
<specific: file paths, command names, agent names>

## What Went Wrong
<evidence-backed: git log, error outputs>

## Root Causes

| Issue | Root Cause | Category |
|-------|-----------|----------|
| ... | ... | missing-rule / missing-check / knowledge-gap / no-verify / wrong-assumption |

## Rule Violations Found
<list violations from Phase 3, or "None">

## Knowledge Gaps
<list things agents didn't know that should be documented>

## Action Table

| # | Action | Type | Due | Verification |
|---|--------|------|-----|-------------|
| 1 | ... | rule-update / check-script / knowledge-doc / agent-prompt / process-change | next session | ... |

Action types: `rule-update` | `check-script` | `knowledge-doc` | `agent-prompt` | `process-change` | `investigate`

## Knowledge Updates Needed
<list docs to update and what to add>

## Workstream Updates
<what to write in SYSTEM.md "Current State" + any workstream docs>
```

---

## Phase 6: Present and Cleanup

**Present in this order** (do NOT ask passive questions — lead with findings):
1. Summary (3 bullets)
2. Root causes table (most valuable part)
3. Any recurrences from Phase 4 check 1 — lead with these if found, they are the headline
4. Action table
5. Rule violations

**Session cleanup checklist:**
- [ ] Update `docs/SYSTEM.md` "Current State" section — what changed, next steps
- [ ] Append to any relevant workstream docs
- [ ] Commit `.claude/`, `docs/`, `agent_reports/` to main with message `retro: <date> <branch>`
- [ ] Run `gh issue list` — flag open issues to update or close
- [ ] If session > 3 hours or > 20 commits, suggest `/compact`
