Session Retro

Session Retrospective

Review the current conversation to surface actionable learnings, then help the user decide what to persist.

Step 0: Cross-session pattern check

Before scanning the current conversation alone, look at the last 3-5 retros (if any) in .claude/retros/ or in project-memory. If a pattern is repeating across multiple sessions — same friction, same kind of error, same skill gap — surface it specifically. Cross-session patterns are higher-signal than one-off observations.

Step 1: Scan the Conversation

Read through the full conversation and extract items in these categories:

Errors & Fixes

• What broke and how it was fixed
• Root causes that were non-obvious
• Workarounds that succeeded after initial approaches failed

Repeated Patterns

• Sequences of tool calls or steps that appeared 3+ times
• Copy-pasted prompts or instructions given to subagents
• Manual processes that could be automated

User Corrections

• Times the user redirected your approach
• Explicit preferences stated ("always do X", "never do Y", "I prefer Z")
• Implicit preferences revealed by approvals/rejections

Knowledge Gained

• Codebase facts discovered (file locations, conventions, gotchas)
• External system behaviors learned (API quirks, tool limitations)
• Configuration or environment details that affected the work

Workflow Friction

• Steps that took multiple attempts
• Places where context was lost or repeated
• Tasks that would benefit from a hook, skill, or MCP server

Step 2: Present Findings

Group findings into a concise table:

## Session Retrospective

### Potential Memory Entries (persist across sessions)
| # | Finding | Type | Source |
|---|---------|------|--------|
| 1 | R2 bucket uploads need --content-type flag | codebase fact | error at turn 12 |
| 2 | User prefers max 10 concurrent agents | preference | explicit instruction |

### Potential Skill Opportunities (automate repeated work)
| # | Pattern | Frequency | Effort |
|---|---------|-----------|--------|
| 1 | Batch sentence generation with 10-agent concurrency | 5 times | medium |

### Potential Skill Improvements (existing skills that fell short)
| # | Skill | Issue | Suggestion |
|---|-------|-------|------------|
| 1 | generate-japanese | No furigana validation step | Add post-gen validation |

### Potential Hooks / Automation
| # | Trigger | Action | Why |
|---|---------|--------|-----|
| 1 | PostToolUse:Write on *.json | Validate JSON schema | Caught 3 malformed files |

Omit any category that has zero findings — don't show empty tables.

After the table, give a one-line recommendation for the single highest-impact item.

Step 3: Ask What to Implement

Prompt: "Which items should I act on? Enter numbers by category (e.g., 'memory 1,2' or 'skill 1') — or 'all' to do everything."

Step 3.5: Convergence check (optional but recommended)

If you've extracted findings in 2+ rounds (e.g., re-running the retro after acting on the first set), invoke convergence-detect to decide whether another extraction round is worth it. Signals: output size shrinking, new-finding ratio dropping, content similarity to the last round rising. Stop when all three fire.

If convergence-detect is not installed, fall back to the heuristic: stop when a fresh round produces ≤20% new findings.

Step 3.6: Auto-apply mode

If the user invokes with --yes (or pastes "apply all"), skip per-item confirmation in Step 3 and go straight to Step 4 for every selected item. Surface a summary at the end: "Applied N items — M memory entries, K skill changes, J hooks. Skipped P items requiring user input."

Step 4: Execute

For each selected item:

• Memory entries → Write per the [project-memory schema](../../../docs/project-memory.md): frontmatter with name/description/type and source: session-retro, body in the type-specific template, dedupe against existing entries, update MEMORY.md index.
• Skill opportunities → Draft a new SKILL.md following the Anthropic Agent Skills format. Keep it lean — the user can iterate later.
• Skill improvements → Read the existing skill, apply the suggested change, show a diff.
• Hooks / automation → Create the hook script and add the entry to the agent's settings file, following the agent-specific schema.

After applying changes, summarize what was written and where.

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: momentmaker
• Source: momentmaker/kaijutsu
• License: MIT
• Homepage: https://kaijutsu.dev/

Install and usage instructions live in the source repository linked above.