--- name: project-retrospective description: Use when a project needs multi-session retrospective analysis — after milestones, before starting a new phase, when vision drift is suspected, or every 3-5 sessions. Triggers: user says "retro", "run a retro", "since-last-retro"; asks to analyze patterns, recurring mistakes, or correction trends across multiple sessions; says "how did we get here" or "project history" in a project-arc context (not single-file diffs or README edits); or notes that MEMORY.md has drifted from what actually happened across sessions. NOT for: single-session review, MEMORY.md cleanup, retro templates, or git-level file diffs. argument-hint: [full | since-last-retro | last-N] --- # Project Retrospective Analyze a project's session history by dispatching parallel historian agents to read each export, then synthesizing their findings into a structured analysis document. The value is in the **extraction criteria** — domain-specific signals tuned for Claude Code session exports, not generic summarization. ## Modes Two modes, differentiated by **output format** (not historian cost): | Mode | Output | When to Use | |------|--------|-------------| | **full** | Standalone ANALYSIS (superset, safe to delete prior) | Phase transitions, major incidents, no prior retro exists, reset the chain | | **incremental** | Delta UPDATE (references prior retro, never delete prior) | Periodic check-ins (every 3-5 sessions), ongoing projects with an existing retro baseline | Both modes reuse prior historian work when a prior retro exists — only NEW exports get fresh historians. The difference is what the synthesizer produces: a standalone document vs. a delta document. ## Arguments Parse `$ARGUMENTS` to determine scope and mode: | Argument | Behavior | |----------|----------| | *(none)* | **Context-aware default.** Check for prior retros first (Phase 1.5). If a prior retro exists, default to **incremental**. If no prior retro exists, default to **full**. | | `full` | **Explicit full mode.** User override — produce a standalone ANALYSIS. Still reuse prior historian work (only dispatch historians for new exports). | | `since-last-retro` | **Explicit incremental mode.** Produce a delta UPDATE against the prior retro. | | `last-N` | **Full mode** scoped to the N most recent exports only. Always dispatches fresh historians for all N exports — does not reuse prior retro content. Skip Phase 1.5 entirely. Use for focused recent-session analysis. | If the argument doesn't match any of the above, echo it back and ask what was meant. **User override is final.** If the user explicitly says `full`, produce a full ANALYSIS — don't argue or suggest incremental. The context-aware default only applies when no argument is given. ## Phase 1: Discover & Validate Exports Find all session exports: ``` ~/.claude/exports/{project-name}/*.txt ``` Sort by filename (date-prefixed = chronological). If `last-N` was provided, take only the last N. **No exports directory or no .txt files:** Stop immediately. Report the issue and suggest the user run `/export` in prior sessions. Do NOT proceed with zero exports. **Some exports missing:** List what was found, proceed with available files, and note gaps in the final output. ## Phase 1.5: Detect Prior Retro In both modes, find the most recent full retro document: ``` docs/retros/*-PROJECT-HISTORY-ANALYSIS.md ``` **Fallback for pre-v2 projects:** If `docs/retros/` has no matches, also check `docs/*-PROJECT-HISTORY-ANALYSIS.md` (pre-v2 output path). If found there, move it to `docs/retros/` first, then proceed. **If no prior retro exists anywhere:** - **Incremental mode:** Report this and switch to full mode automatically. Incremental requires a baseline. - **Full mode:** Proceed normally — all exports need fresh historians. **If prior retro found:** 1. Read it fully — it contains the synthesized analysis of previously-analyzed sessions. 2. Extract the session range it covers (from the `**Sessions:** ` header line). 3. Determine which exports are NEW (not covered by the prior retro's session range). 4. If zero new exports exist since the prior retro: report "nothing new to analyze — prior retro is current" and stop. This applies to both modes — re-synthesizing the same data produces equivalent output. 5. **Full mode:** The prior retro's content serves as pre-computed extraction for already-analyzed sessions (see Phase 2). **Chaining semantics:** Incremental always chains from the last *full* retro (ANALYSIS file), never from a prior *incremental update* (UPDATE file). This means multiple incremental updates can accumulate between full retros. Each delta is independently interpretable against the same baseline. To reset the chain, run a full retro. **Gaps in prior retro:** If the prior full retro noted missing exports (sessions it couldn't analyze), those gaps are permanent unless a new full retro is run. Incremental mode does not backfill gaps — it only analyzes exports newer than the prior retro's session range. ## Phase 2: Spawn Historians (Parallel Background Agents) **Incremental mode:** Launch one background agent per NEW export only. **Full mode with prior retro (Phase 1.5 found one):** Only dispatch historians for exports NOT covered by the prior retro. The prior retro's content serves as pre-computed extraction for already-analyzed sessions — pass it to the synthesizer in Phase 3 alongside the new historian reports. This gives full-mode superset output with incremental historian cost. **Full mode without prior retro:** Launch one background agent per export (all exports). Use the literal `Agent` tool (not TaskCreate, not TeamCreate) with these exact parameters: ``` Agent( description: "Historian: {SESSION_LABEL}", prompt: , model: "opus", subagent_type: "general-purpose", run_in_background: true ) ``` **Why opus:** Exports are 50-200KB (30-65K tokens). Opus handles deep extraction from large documents. Haiku/sonnet miss nuance. If opus is unavailable, use the best model accessible — expect lower extraction quality from large exports. **Why NOT TeamCreate:** Race conditions with member registration. **Why NOT TaskCreate:** Tasks track progress. The `Agent` tool dispatches work. ### Historian Extraction Template Each historian receives this prompt with `{FILE_PATH}` and `{SESSION_LABEL}` filled in: ``` Read the COMPLETE file at {FILE_PATH}. This is a Claude Code session export from {SESSION_LABEL}. Session exports are plain text with collapsed tool calls — Agent prompts, memory writes, and subagent details are behind expansions and NOT visible. Extract what IS visible: user messages, Claude responses, decisions, corrections, and deliverables. Extract the following. Include brief quotes or concrete references — not vague summaries. 1. **How session started**: First user prompt. Continuation or fresh? How was context established? 2. **Original intent vs actual**: What was planned vs what happened. Why different? 3. **Key decisions**: Technology, architecture, process decisions — with rationale and whether they held or were reversed. 4. **User corrections**: Every time the user caught Claude making a mistake. QUOTE the correction verbatim. This is the most valuable data — pattern these by type. 5. **Mistakes and anti-patterns**: What went wrong, root causes, systemic issues (not just one-offs). 6. **Quality moments**: When user pushed for higher rigor — what was the ask and what was Claude's response? 7. **Roadmap evolution**: How did the plan/scope change during the session? 8. **Deliverables**: Files created/modified, PRs opened/merged/closed, documents produced. 9. **Handoff**: What was stated as the next session's task? Deferred items? Output as clean markdown. No preamble. Return TEXT DATA only — do NOT write any files. ``` **Historian failure:** Relaunch once. If it fails again, proceed with available reports and note the gap. Do NOT approximate from other historians or from MEMORY.md — relaunch, don't guess. ## Phase 3: Synthesize After ALL historians complete, combine reports into a single analysis. **Synthesizer delegation:** If fewer than ~15 historian reports, the orchestrator can synthesize inline. For 15+ reports, delegate to a dedicated opus synthesizer agent — the combined reports plus prior retro content may exceed comfortable inline processing. Pass all historian reports and (if applicable) the prior retro content in the synthesizer's prompt. **Full mode** uses the Full Synthesis Template. **Incremental mode** uses the Incremental Synthesis Template. **Full mode with prior retro input:** The synthesizer needs BOTH the new historian reports AND the prior retro content. The prior retro provides the deep extraction for already-analyzed sessions; the new historian reports cover the delta. The synthesizer must treat both as equal primary sources and produce a standalone superset ANALYSIS — not a delta, not a summary of the prior retro with new sections appended. Re-synthesize the full narrative from all available data. **Incremental mode input:** The synthesizer needs BOTH the new historian reports AND the prior retro content (read in Phase 1.5). If delegating synthesis to a subagent, include the prior retro text in its prompt — the subagent doesn't have Phase 1.5 context. ### Full Synthesis Template ```markdown # {Project Name} — Project History Analysis **Generated:** YYYY-MM-DD HH:MM UTC | **Sessions:** range | **Agents:** N+1 ## 1. Original Vision vs Current State The user's original vision, how it evolved, honest drift assessment — were changes justified or accidental? ## 2. Roadmap: Original vs Actual | Session | Planned | Actual | Deviation Justified? | ## 3. Decision Log | Session | Decision | Rationale | Status (held/reversed/superseded) | ## 4. Mistakes and Corrections Pattern mistakes by type. Common Claude behavioral patterns to seed: - Deferral disguised as process (effort avoidance) - Overconfidence without verification (asserting not checking) - Not following own rules (loaded but not consulted) - Fabricated/unverified claims (training data biases) Also surface any project-specific patterns beyond these. Count instances per pattern — reveals systemic issues. ## 5. User Teaching Moments Recurring lessons the user had to teach. These are the user's priorities and standards — future sessions must internalize them. ## 6. What's Valid Now Current state: artifacts, what's on main, what's pending. Clear inventory. ## 7. Recommended Next Step Justified from FULL history, not just latest MEMORY.md. If history suggests a different priority than MEMORY.md, say so. ``` ### Incremental Synthesis Template ```markdown # {Project Name} — Project History Update **Generated:** YYYY-MM-DD HH:MM UTC | **New sessions:** range | **Prior baseline:** prior-retro-filename **Cumulative sessions:** full-range | **Agents:** N+1 ## Prior Retro Summary One-paragraph summary of what the prior retro established as the project state, key patterns, and outstanding issues. ## 1. What Changed Since Last Retro New decisions, direction shifts, scope changes in the delta sessions. Reference prior retro for context where relevant. ## 2. New Decisions | Session | Decision | Rationale | Status | ## 3. Correction Pattern Update Carry forward the prior retro's correction patterns. For each pattern: - Prior count + new count = cumulative total - Trend: improving / stable / worsening (compare per-session rate) - Any NEW patterns not in the prior retro get their own entry. ## 4. New Teaching Moments Lessons from new sessions only. Note which are genuinely new vs reinforcement of prior patterns. ## 5. Current State & New Deliverables Updated inventory: what's on main, what's pending, what changed. List files created/modified, PRs merged, documents produced in new sessions. ## 6. Recommended Next Step Justified from cumulative history (prior retro + new sessions). ``` **Cross-session deduplication:** A decision in S1 referenced in S3 appears once with both session numbers. ## Phase 4: Write & Integrate ### Write the analysis Output to the retros directory (create if needed): **Full mode:** `docs/retros/YYYY-MM-DD-PROJECT-HISTORY-ANALYSIS.md` **Incremental mode:** `docs/retros/YYYY-MM-DD-PROJECT-HISTORY-UPDATE.md` ### Update MEMORY.md 1. Add a reference to the retrospective document. 2. Evaluate whether findings warrant new rules or memory: - Project-specific lessons → project memory or CLAUDE.md - General patterns (cross-project) → propose rule in `~/.claude/rules/` - Existing-rule violations → note the enforcement gap, don't duplicate 3. Threshold: happened twice, or high-severity once. ### Commit Commit the analysis and any memory updates. ## Deletion Semantics | Mode | Prior retro safe to delete? | Why | |------|-----------------------------|-----| | **Full** | Yes | Full output is a superset — contains everything the prior retro had plus more. Prior becomes redundant. | | **Incremental** | **Never** | Incremental output is a delta — it references and builds on the prior retro. Deleting the prior loses the deep extraction from earlier sessions permanently. The chain of incremental retros forms a linked history. | ## Anti-Patterns - **Single agent for all exports** — each agent needs full context for one export. Combining loses depth. - **Compressing historian reports** — the synthesizer needs full detail for cross-session patterns. - **Skipping "User corrections"** — the most valuable signal. Without it, the retro is generic. - **Writing from MEMORY.md** — MEMORY.md is derivative. Exports are the primary source. - **TeamCreate for historians** — race conditions with member registration. Use background Agents. - **Haiku/sonnet for historians** — exports are 50-200KB. Cheaper models miss nuance in long documents. - **Summarizing instead of extracting** — "summarize the session" produces generic output. The 9-point extraction template IS the skill's value. - **Re-analyzing old sessions in incremental mode** — the whole point of incremental is O(delta). If you're spawning historians for sessions the prior retro already covers, you're doing it wrong. - **Fresh historians for already-extracted sessions** — if a prior retro exists, its content IS the extraction for those sessions. Dispatching new historians to re-read the same exports wastes opus agents and produces equivalent output. Only dispatch historians for sessions the prior retro doesn't cover. - **Hardcoding default mode without checking project state** — the default (no argument) should check whether prior retros exist before committing to full or incremental. A blind default ignores available information. - **Deleting prior retro after incremental** — incremental output is a delta, not a superset. The chain breaks. - **Running incremental without a baseline** — if no prior retro exists, switch to full mode. Don't produce a delta with nothing to delta against.