project-retrospective

What this skill does

# 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:** <range>` 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: <extraction template below>,
  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