retro

The user has asked for a retrospective. Look back at a coding session and propose improvements to the agent's environment — checks, pointers, steering files, tool access — so the next session goes better. The code the session produced is out of scope.

This is the counterweight to evolve-claude-md: that skill adds durable knowledge to CLAUDE.md after every session; this one finds what should have been a lint, a doc behind a pointer, or nothing at all.

Hard gate: report-only. Propose edits, checks, and cuts; make none of them. The user applies what they accept.

Scope

• Session. The current session by default — the conversation context you already hold. With --session <id|path>, read that transcript instead: ~/.claude/projects/<project-slug>/<id>.jsonl (or under $CLAUDE_CONFIG_DIR/projects when set). Transcripts are large; don't read one end to end. Grep for the signals in the table below (repeated reads of the same path, failed commands, retries, long search runs) and read around the hits.
• Steering files. The target repo's CLAUDE.md (or the canonical AGENTS.md it redirects to), its docs/, and any skill or hook the session used. Add ~/.claude/CLAUDE.md with --global, or whenever a finding clearly belongs to every project rather than this one.
• Existing guardrails. Before proposing any check, read what the repo already runs: its CI workflow, pre-commit config, lint scripts, test command. A check that exists but is unwired or silently broken is the finding — not a reinvention.

What to look for

Routing ladder. For every finding that would touch a steering file, ask in order: (1) can a deterministic check enforce it? (2) is it reference material that belongs behind a pointer? (3) only then, is it a judgement call that earns prose? Default to the check. A rule stated in CLAUDE.md is advisory; a rule enforced by a lint is a fact.

Output

Lead with the session in two lines: what it was doing, and the one thing that cost it the most.

Then one entry per finding, ordered by severity (a missing guardrail or a repeated mistake outranks a slow lookup):

### [category] — short label                               severity: high | med | low
Evidence: what happened in the session (quote or tool-call count; file:line for steering text)
Proposal: the concrete change — the check to add, the pointer text, the lines to cut
Cost: what applying it takes (minutes / a new script / a settings change the user must paste)

Close with a summary table — category, label, severity, cost — and a one-line tally of what the proposals would do to the steering file's size (lines added vs. cut). If the session surfaced nothing, say so in one line and stop; do not manufacture findings.

Secrets and PII. Transcripts and steering files can hold credentials, tokens, and third-party personal data. Never quote a credential into the report; name the finding without the value. The archived report inherits the sensitivity of whatever it quotes — say so when a finding quotes session text that identifies someone.

Archive

Unless --no-archive was passed: after emitting the report, write it verbatim to <repo-root>/.ai/reviews/<YYYY-MM-DD>-retro[-<session-slug>].md (mkdir -p "$(git rev-parse --show-toplevel)/.ai/reviews"; suffix -2, -3… on filename collision). Best-effort — if the cwd isn't a git repo or the write fails, add a one-line note and move on; never alter the report itself. Probe the ignore with the file path at repo root, not the bare directory: if git check-ignore -q "$(git rev-parse --show-toplevel)/.ai/reviews/probe.md" exits non-zero, warn and suggest adding .ai/ to .gitignore. (git check-ignore -q .ai false-negatives for the directory-form .ai/ pattern whenever the directory does not yet exist.)

Provenance header. Prepend a YAML block to the archived file only (never to the report shown to the user):

---
skill: retro
skill-version: <toolkit version>
reviewed-repo: <repo basename> @ <short SHA>[ (dirty)]
cli: <claude --version>
date: <YYYY-MM-DD>
---

Collect the values with:

SD="${CLAUDE_PLUGIN_ROOT:+$CLAUDE_PLUGIN_ROOT/skills/retro}"; SD="${SD:-$HOME/.claude/skills/retro}"
cat "$SD/.version" 2>/dev/null || echo unknown    # skill-version ("unknown" under plugin install)
git rev-parse --short HEAD 2>/dev/null || echo unknown
git status --porcelain 2>/dev/null | head -1      # non-empty → append " (dirty)"
claude --version 2>/dev/null || echo unknown

.version is written into the deployed skill dir by sync.sh push; it is absent under a plugin install, which is expected. Resolve any value that fails to unknown — never drop the key, and never let a failed lookup block or alter the archive.

Anti-rationalization

Verification

• No file outside .ai/reviews/ was modified.
• Every proposal that touches a steering file passed the routing ladder, and the entry says which rung it landed on.
• Each "automated check" finding names the existing guardrail it builds on (or states that none exists).
• No credential or token value appears in the report.
• Findings are ordered by severity, and the closing tally states lines added vs. cut.