Retrospective: $ARGUMENTS

The kit generates evidence about itself constantly — /implement writes a Deviation Report into every plan, /diagnose records root causes, /handoff snapshots decisions, /arch-health ranks rot. This skill is the only consumer: it reads that exhaust, finds what recurs, and folds the lesson back into the artifact that will prevent the next occurrence. One occurrence is an accident; two is a pattern; a pattern with no rule against it is a scheduled repeat.

$ARGUMENTS optionally scopes the retro (an epic name, a date range like "last month", a theme like "testing"); empty = everything since the previous retro report (or all history on the first run).

This skill edits kit-config artifacts only (rules, PROJECT.md, CONTEXT.md pointers, retro reports, and agent-memory entries — compression after promotion only, never new facts) — never application code, and never a skill file without explicit confirmation.

Phase 0 — Load profile

1. Read .claude/PROJECT.md — Plans/backlog location, Archive location, Artifact git policy. If missing or TEMPLATE, fall back to the root CLAUDE.md (always in context) when it carries those locations — note you're running without a kit profile; STOP: run /bootstrap first only if neither has them.
2. Read CONTEXT.md (if present) so lessons are phrased in the project's language.
3. Find the previous retro report at the Plans location (*-retro.md) — its date bounds this run's window, and its "Lessons applied" list must not be re-proposed.

Phase 1 — Harvest the evidence (read-only)

Collect from the window, citing every source file:

• Archived plans (Archive location + backlog): every ## Implementation Log and Deviation Report table — what did plans get wrong about the code?
• Plan status frontmatter — PARTIAL / BLOCKED plans and their notes.
• Handoff docs — "Key decisions" and "Open questions" sections: what kept being decided mid-flight instead of at planning time?
• Diagnose / arch-health / audit reports at the Plans location — root causes and confirmed findings.
• git log over the window (Bash, read-only) — revert commits and fix-of-a-fix chains (fix, revert, repeated touches of one file in short succession).
• Agent memory — .claude/agent-memory/**/MEMORY.md and the entry files behind it, plus every other tree: agent stores are written relative to the session's cwd, so a monorepo or a nested package usually has several (**/.claude/agent-memory/). Find them before reading them; a retro that reads one tree silently retros one corner of the project. This source is different in kind from the others — the agents have already done the mining, and the (N×) counters are recurrence already counted, which is the evidence Phase 2 otherwise has to assemble by hand.

For a large window, delegate the sweep to a read-only Explore agent per source category and collect its citations. Do not paraphrase from memory — every harvested item carries its source path.

Phase 2 — Mine for recurrence (the evidence gate)

Group harvested items into candidate patterns. A pattern requires ≥2 independent occurrences, each cited — one-off events are logged under "Observed once (watch)" and are NOT actionable this run. Typical pattern shapes:

Classify each candidate against docs/agent-failure-modes.md — the catalog of systematic agent failure modes. A pattern that matches a mode (premature closure, silent scope narrowing, confabulated specifics, thrash, …) inherits that mode's documented countermeasure as the default proposal; cite the mode number in the lesson. A recurring pattern that matches no mode and no kit countermeasure is doubly valuable — flag it as a candidate addition to the catalog itself.

A memory entry at (≥3×) is a promotion candidate by definition — three sessions hit it and the store is still the only thing defending against it. Route it like any other lesson in Phase 3 (a rule line, an agent stance, a skill step), and on the user's confirmation compress the entry to a pointer: one line naming the rule that now owns it, with the counter kept as provenance. Memory is the waiting room; a lesson that lives there forever is one the project keeps re-learning. Leave (1×) and (2×) entries alone — they are still accruing evidence.

Then run each candidate through the finding-verifier agent (batches of 3–4; default REFUTED on ambiguity) — a "recurring pattern" built on coincidence wastes a rule slot forever. Only CONFIRMED patterns proceed. A memory entry's counter is evidence that it recurred, not evidence that the lesson is right: verify it like the rest.

Phase 3 — Route each lesson to the artifact that prevents the repeat

The fix goes where the next session will actually meet it:

One lesson → one target. A lesson that "belongs everywhere" belongs in the most specific place it will be read.

Phase 4 — Propose, confirm, apply

Present the confirmed lessons as a table: pattern (with its ≥2 citations) → proposed edit → target file. Then confirm via AskUserQuestion — batch related lessons, but never bundle a skill-file edit with rule/profile edits in one question. Apply only confirmed edits:

• PROJECT.md / rules — apply directly with Edit (lean, imperative, in the target file's existing voice; a rule line the next session must obey, not an essay).
• Skill files — apply only on explicit confirmation, following /writing-skills conventions.
• CONTEXT.md / ADRs — route to /domain-model; don't write them here.
• Agent-memory entries — only the compression the promotion earned: replace the body with a pointer to the artifact that now owns the lesson, keep the counter and the index line. Never add a fact to an agent's store from here; that store is the agent's, and a fact you inject has no occurrence behind it.

Rejected lessons are recorded in the report with the user's reason — a rejection is itself knowledge (don't re-propose it next retro).

Phase 5 — Write the retro report

Write <plans>/<YYYY-MM-DD>-retro.md (its git policy per PROJECT.md):

# Retro — <window/scope>

## Lessons applied
- <pattern> (evidence: path, path) → <edit made> in `<file>`

## Rejected (do not re-propose)
- <pattern> — <user's reason>

## Observed once (watch)
- <event> (evidence: path) — becomes actionable if it recurs

## Health notes
- <plans DONE/PARTIAL/BLOCKED counts, deviation rate trend vs previous retro if available>

Hard rules

• ≥2 cited occurrences or it's not a pattern. Singles go to "Observed once" — never into a rule.
• Verify before proposing. Every pattern passes finding-verifier; ambiguity = REFUTED.
• User confirms every edit. No rule, profile, or skill change lands without confirmation; skill edits need their own explicit yes.
• Never edit application code. Code fixes route to /refactor / /prepare — this skill changes what the kit knows, not what the app does.
• Respect settled decisions. A pattern already covered by an ADR or a previous retro's rejection is surfaced as "settled — reopen?" — never silently re-applied.
• Facts from PROJECT.md. Locations and policies come from the profile — never hardcoded.

Cross-reference

• Upstream evidence: /implement (Deviation Reports), /diagnose, /handoff, /arch-health, /close-epic (run it first to settle the epic; then retro it).
• Lesson sinks: /domain-model (terms/ADRs), /writing-skills (skill edits), PROJECT.md and .claude/rules/* (direct edits here).