session-retro

Session Retro

A session retrospective that turns conversation mistakes into durable process improvements, and successful patterns into reusable skills.

Why this matters

Without retro, the same mistakes repeat across sessions — Claude gets corrected, apologizes, and forgets by next conversation. Retro breaks this cycle by tracing errors to their source (a skill, CLAUDE.md, memory, or tool behavior) and proposing concrete fixes that persist.

Process

1. Scan conversation for correction signals
2. Classify: errors found → Path A | smooth session → Path B
3. For each finding: analyze → attribute → propose action
4. Run Path C (token efficiency analysis)
5. Present report with action proposals
6. Ask user which actions to execute
7. Ask user if they want to save the report

Step 1: Scan for Correction Signals

Search the conversation for moments where the user corrected or redirected Claude's behavior.

Correction signal patterns (not exhaustive — use judgment):

• Direct corrections: "wrong", "no", "that's not right", "incorrect"
• Redirections: "shouldn't it be...", "why did you use X instead of Y", "you missed..."
• Repeated instructions: user restating something they already said
• Frustration cues: "wrong again", "still failing", "I already said..."
• Questions challenging behavior: "why", "which process did you follow", "the skill says..."
• Explicit review requests: "review the session log", "trace what happened..."

Also scan for silent corrections — places where the user quietly fixed something Claude should have done (e.g., user manually ran a command Claude skipped).

Step 2: Classify the Session

• Errors found → Path A (analyze each error)
• No errors found → Path B (extract successful patterns)
• Mixed → Do both Path A and Path B After completing Path A and/or Path B, proceed to Path C (step 4).

Path A: Error Analysis

For each correction found, build a root cause analysis:

2a. What happened?

State factually: what did Claude do, and what should it have done? No defensiveness, no hedging. Just the facts.

2b. Trace the source

Identify which document or mechanism should have guided the correct behavior:

Source type	How to check
Skill	Was a skill invoked? Read the skill — does it clearly cover this case?
CLAUDE.md	Does project or global CLAUDE.md have instructions for this?
Memory	Is there a relevant memory file that should have applied?
Tool behavior	Was a tool used incorrectly, or was the wrong tool chosen?
No source	No existing document covers this case

Read the actual source file to verify — don't rely on memory of what it says.

2c. Attribute the cause

Determine which category the error falls into:

1. Source is unclear — The document exists but is ambiguous or poorly structured, making it easy to misinterpret. (Example: a default rule buried in an "override" subsection)

2. Source is missing — No document covers this scenario. Claude had to improvise and guessed wrong.

3. Execution drift — The document is clear, but Claude didn't follow it. This happens when instructions are long or when shortcuts seem reasonable in context.

4. One-off mistake — A simple slip (wrong file path, typo, etc.) with no systemic cause.

2d. Propose action

Based on the attribution:

Attribution	Proposed action
Source unclear	Update the source — rewrite the ambiguous section with clearer structure
Source missing	Create source — new skill, memory, or CLAUDE.md section
Execution drift	Save feedback memory — a concise rule that catches attention on future reads
One-off mistake	No action needed — note it but don't over-engineer a fix

For each action, specify:

• Which file to modify (exact path)
• What to change (before/after or description)
• Why this fix prevents recurrence

Path B: Success Pattern Extraction

When the session went smoothly, look for patterns worth preserving:

1. Multi-step workflows that succeeded — could they become a skill?
2. Novel tool combinations — a sequence of tools that solved a problem efficiently
3. Decisions that avoided problems — defensive choices that paid off
4. Reusable subagent prompts — agent dispatches that returned good results

For each pattern, assess:

• Frequency: Will this come up again? (one-off → skip; recurring → extract)
• Complexity: Is it complex enough that a skill adds value? (trivial → skip)
• Brittleness: Would the pattern break without the skill guiding it? (fragile → extract)

Only propose extraction for patterns scoring high on at least 2 of 3 criteria.

Path C: Token Efficiency Analysis

Runs after Path A/B. The goal is to find token waste within this session and suggest concrete improvements for future sessions.

Claude Code cannot access exact token counts, so use heuristic estimation based on observable signals: file sizes read, tool call count, subagent dispatches, and conversation round-trips. Focus on actionable patterns, not precise numbers.

4a. Scan for Cost Signals

Review the conversation for these patterns:

Signal	What to look for
Subagent model mismatch	Opus agent dispatched for tasks a cheaper model could handle (simple grep, file lookup, straightforward code generation)
Redundant operations	Same file read multiple times, identical or near-identical searches repeated
Oversized reads	Large files (>500 lines) read in full when only a small section was needed
Agent overuse	Subagent spawned for tasks achievable with direct Grep/Glob/Read (see 4c for skill-required dispatches)
Sequential round-trips	Multiple dependent tool calls that could have been parallelized, or information gathered piecemeal that could have been collected in one pass
Wasted exploration	Dead-end research paths that could have been avoided with a better starting question

4b. Assess Each Finding

For each cost signal found:

1. What happened: Describe the specific operation(s)
2. Why it was expensive: Which factor — model tier, data volume, or round-trips
3. Better alternative: What could have been done instead
4. Estimated saving: high (different model tier or eliminated agent), medium (fewer round-trips or targeted reads), low (minor optimization)
5. Proposed action: [save feedback memory / update skill / update agent definition / update CLAUDE.md / no action]

4c. Subagent Dispatch Review

If no subagent dispatches occurred in this session, skip this section.

Review each subagent dispatch in the session:

1. Was the agent necessary? Could the task have been done with direct tool calls instead? Exception: if a skill's instructions explicitly require dispatching a subagent (e.g., preflight dispatching platform expert agents, todos-review using Explore), that is expected behavior — do not flag it as overuse.
2. Was the subagent type appropriate? (e.g., using Explore for a task that only needed Grep)
3. Was the model tier justified? Check the actual model used — subagents may have a model set in their agent definition frontmatter, not just via the dispatch model parameter. If the agent definition pins a model, use that as the actual tier for cost assessment. When a skill required dispatching that specific agent type and the agent definition pins the model: do not blame the caller — but DO evaluate whether the skill or agent definition itself is over-specified. If so, propose updating the skill or agent definition as an actionable finding (e.g., "agent X pins opus but its tasks only need sonnet-level reasoning — consider changing the agent definition").

Report Format

Present the report directly in conversation (not as a file):

# Retro: YYYY-MM-DD

## Findings

### 1. [Short title of error or pattern]
- **What happened**: [factual description]
- **Root cause**: [source file path + specific section, or "no source"]
- **Attribution**: source unclear / source missing / execution drift / one-off
- **Proposed action**: [action type] — [brief description]
- **Details**: [what specifically to change]

### 2. [Next finding...]
...

## Summary
- Errors: N (action needed: N, no action: N)
- Successful patterns: N (worth extracting: N)

## Proposed Actions
1. [Action type] [target file] — [one-line description]
2. ...

## Token Efficiency (omit if Path C was skipped or no cost signals found)

### Cost Signals
- Subagents dispatched: N (by type: Explore: N, ios-dev: N, ...)
- Large file reads (>500 lines): N
- Redundant operations: N
- Avoidable round-trips: N

### Optimization Opportunities
1. [Specific suggestion] — estimated saving: high/medium/low
   - **Proposed action**: [save feedback memory / update skill / update agent definition / update CLAUDE.md / no action]
   - **Target**: [file path or "feedback memory: ..."]
2. ...

### Subagent Dispatch Issues (if any)
- [Agent description] used [type/model] → [recommend alternative] because [reason]

After Presenting the Report

1. Ask which actions to execute. Combine actions from both "Proposed Actions" (Path A/B) and "Optimization Opportunities" (Path C) into a single numbered list for user approval. The user may approve all, some, or none. Only execute approved actions.

2. Execute approved actions. For each:

   • Read the target file before modifying
   • Make the change
   • Show a brief summary of what changed

3. Ask if user wants to save the report. If yes, save to docs/retro/YYYY-MM-DD.md (create the directory if needed). If no, the report lives only in conversation history.

Edge Cases

• Very short session (< 5 exchanges, where one exchange = one user message + one assistant response): Tell the user there's not enough context for a meaningful retro. Offer to note any specific concern instead.

• User was wrong, not Claude: If investigation reveals the user's correction was based on a misunderstanding, say so respectfully with evidence. Don't create process fixes for non-problems.

• Multiple errors with same root cause: Group them under one finding. One fix should address all instances.

• Sensitive corrections: If the user's correction was about tone or communication style (not technical), save as a feedback memory rather than a skill update.