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:
- Read it fully — it contains the synthesized analysis of previously-analyzed sessions.
- Extract the session range it covers (from the
**Sessions:** <range>header line). - Determine which exports are NEW (not covered by the prior retro's session range).
- 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.
- 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 n