project-retrospective

# 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, Claud