Retro

Context. Gather first

Take session-id, branch, status, recent-commits at -5, and changed-files, the only consumer taking that last one, since a retrospective reasons over what the session actually touched. Probe commands, the one-command-per-call and treat-failure-as-unknown rules, and the $-expansion rationale for gathering at run time rather than pre-computing: ${CLAUDE_PLUGIN_ROOT}/reference/gather.md.

Purpose

The self-improvement loop. Answers: "What happened, what did we learn, and how do we prevent the same mistakes next time?" Every other workflow stage is about the current task; this skill is about the next task, and every task after that.

Three concepts this skill enforces:

1. Analyze. Examine what happened with evidence (transcript metrics, conversation context, feedback regressions)
2. Identify. Find errors, behavioral adjustments, process improvements, and skill/tool candidates
3. Codify. Persist learnings durably (the consuming repo's instruction files and rules, or Claude Code auto-memory for contributor-specific facts)

What this skill is NOT: not a code review (design judgment on current work), not outcome verification (does the change match intent), and not Claude Code's built-in /insights (cross-session usage analytics); this is structured quality analysis with codification.

Paths

Resolve at runtime, never hardcode machine-specific paths:

• Session data root. ~/.claude/projects/<project-slug>/, where <project-slug> is the project's absolute path with every character outside [A-Za-z0-9] replaced by -:

  PROJECT_SLUG=$(pwd -W 2>/dev/null || pwd)          # Windows drive form when available
  PROJECT_SLUG=$(printf '%s' "$PROJECT_SLUG" | sed 's/[^A-Za-z0-9]/-/g')
  SESSION_DATA_DIR="$HOME/.claude/projects/$PROJECT_SLUG"
  

  Verify the directory exists before use; if the computed slug misses, find it by locating the current session's JSONL: ls "$HOME/.claude/projects"/*/"${CLAUDE_CODE_SESSION_ID}.jsonl".

• Transcript: <SESSION_DATA_DIR>/<session-id>.jsonl; subagents: <SESSION_DATA_DIR>/<session-id>/subagents/

• Auto-memory (feedback regression check): <SESSION_DATA_DIR>/memory/. Present only when the consumer uses Claude Code auto-memory; degrade gracefully when absent

• Score history (plugin state): ${CLAUDE_PLUGIN_DATA}/scores/<project-slug>.md. Survives plugin updates, never lands in the consumer's repo

• Parser: ${CLAUDE_PLUGIN_ROOT}/skills/retro/scripts/parse_transcript.py (stdlib-only, Python 3.10+)

Step 0: Detect mode

If $ARGUMENTS specifies a mode, use it. Otherwise infer from context; when the session is long or degraded, or compaction has occurred, prefer quick; ambiguous → session. Read the mode's context file before proceeding.

Step 1: Execute the mode

Follow the selected context file. Each mode has its own phases, outputs, and interactive checkpoints.

Reference index. Load on demand

Step 2: Handoff

After the retrospective:

Multi-session awareness

When the sibling handoff skill's save-points exist (the resolved <memory_dir>/handoffs/, default .work/handoffs/; or the consuming repo's documented location), the retro spans the whole session CHAIN, not just the current session: the parser's --chain-from walks previous_handoff frontmatter pointers backwards from the newest handoff file and aggregates metrics across every chained transcript. See context/session.md Phase 1.

State the discovery basis, and never present a low-coverage chain retro silently. The walk follows previous_handoff pointers, so it stops at the first session that wrote no handoff file, a chain linked by hand-pasted continuation prompts instead of save-points can end after one hop. The parser reports what it saw in chain_coverage (requested / found / available / ratio, where available counts the transcripts present for this project). When ratio is below ~0.5, say so before presenting: name the found and available counts, and offer --sessions with the ids enumerated explicitly. A retro authored from a fifth of the evidence must not read like a complete one.

Offer a durable copy when the session was worth retrospecting. The transcripts this retro reads are retention-swept (cleanupPeriodDays, default 30 days), and the conversation itself has no durable artifact; a session interesting enough to retrospect is the one worth keeping. The default is verified 2026-09-06 against Claude Code 2.1.263 and Data usage, which states that clients store session transcripts locally under ~/.claude/projects/ for 30 days by default and that cleanupPeriodDays adjusts the period. Recheck when that page names a different default, or when a release note names cleanupPeriodDays. When the built-in export command resolves in your session, close by offering the one-line export /export <memory_dir>/exports/<YYYYMMDDTHHMMSSZ>-<topic>.txt, after verifying the memory root's self-ignore guard (a .gitignore containing *, created and announced when absent). Offer only, never run: built-ins are user-invoked, and nothing records or verifies that the export happened.

What this skill does NOT do

• Does not run builds or tests. That's the consuming repo's verify stage
• Does not review code quality. That's its review stage
• Does not write scores or reports into the consumer's repo. Plugin state stays in ${CLAUDE_PLUGIN_DATA}; only user-approved codifications (rule edits, memory entries) land outside it
• Does not read a consumer-supplied scoring rubric. The five dimensions are fixed plugin identity, not consumer config, and there is no seam to swap them. What adapts is what each dimension scores against (your repo's conventions, session-type calibration), never the dimensions themselves.

Gotchas

• Run all phases by default in session mode. Skip metrics only when the parser fails or the user asks
• Always include skill-candidate and follow-up-candidate analysis, even when the conclusion is "no candidates this session"
• Codify follows the workflow too. Adding a bullet to a rules file requires verification, not just pasting
• Phase 4 is an interactive checkpoint, never persist codifications without explicit user approval