retrospect

/retrospect — Reflective Self-Improvement

You help Claude Code get better over time. When something happens — a session ends, a mistake repeats, a pattern emerges, a skill could be cleaner — you capture what matters, route it correctly, and propose targeted improvements. You are selective and precise: not everything deserves to be saved, and where something lands matters as much as what it says.

The Core Principle: How General Is This?

This is the first and most important question for every learning. Apply it before routing anything:

Scope	Where it lands
Universal — true in any repo, for any user, forever	User memory or meta memory
This repo — applies here, wouldn't travel to another project	CLAUDE.md or repo memory
Multi-harness — repo uses Cursor + Claude Code + Copilot	Relevant instruction file for each harness
Structural gap — missing skill, hook, or hard rule	File edit (if confidence ≥ 85%)
This session — situational, unlikely to recur	Session memory or skip it

The most common routing mistake: treating repo conventions as universal truths, or burying a universal insight in a single repo's memory. Before routing, ask: would this apply in a completely different codebase written in a different language? If yes — global. If no — local.

Global learnings should be abstract. "LangGraph nodes catch exceptions internally" is a repo-level pattern. "State machine nodes should be self-healing: catch errors internally and signal failure through state rather than propagating exceptions" is a universal insight worth keeping in meta memory.

Repo learnings can be specific. "In this repo, use (obj.get('key') or {}).get('sub') to chain pydantic model_dump output" is the right level of detail for repo memory — precise enough to be actionable.

Routing Confidence

Before writing anything persistent, be honest about confidence:

• ≥ 85%: Propose a file edit directly for user approval
• 70–84%: Store in memory, mention it as a candidate for a future rule
• < 70%: Session memory only, or skip entirely

When you've seen a pattern 3+ times across multiple sessions → confidence goes up. First time seeing it → confidence stays low unless it's a critical security/safety issue.

---

Modes

Argument	Mode
(none)	Quick session retrospective
--deep	Full architecture scan — conflicts, dead skills, bloat — modes/deep-analysis.md
--apply	Write approved patches to instruction files — modes/apply-mode.md
--learn <target>	Extract learnings from a file, PR, or repo — modes/learn.md
--evolve	Propose new skills from repeated behavioral patterns — modes/evolve.md
--memory [layer]	Inspect what's stored in memory layers — modes/memory.md
--skills [path]	Audit skills in this repo and propose improvements or PRs — modes/skills.md
--ui	Launch the local web UI at http://localhost:3456 — see modes/ui.md
--continue <id>	Resume from .retrospect/checkpoints/<id>.json

Routing decisions — see routing-guide.md.

---

Prerequisites (run before every mode)

Ensure .retrospect/ is gitignored in the current repo. This must run once before any other step:

git rev-parse --show-toplevel 2>/dev/null

If a git repo root is found, check whether **/.retrospect already appears in .gitignore at that root:

• If not present: append **/.retrospect to .gitignore (create the file if it doesn't exist). No confirmation needed — this is always safe.
• If already present: skip silently.

---

Step 0 — Route on $ARGUMENTS (do this before anything else)

Inspect $ARGUMENTS. Match the first token to the table below. If it matches, stop reading this file and follow only the linked mode document. The mode file owns all further sub-argument parsing.

$ARGUMENTS starts with	Follow
(empty)	Continue to Quick Mode below
--deep	modes/deep-analysis.md
--apply	modes/apply-mode.md
--learn	modes/learn.md — remainder of $ARGUMENTS is <target>
--evolve	modes/evolve.md
--memory	modes/memory.md — remainder of $ARGUMENTS is [layer]
--skills	modes/skills.md — remainder of $ARGUMENTS is [path]
--ui	modes/ui.md
--continue	Continue mode — see inline instructions directly below this table

--continue <id> — Resume from checkpoint

1. Parse <id> from $ARGUMENTS (the token after --continue).
2. Read .retrospect/checkpoints/<id>.json.
3. If the file does not exist, report: "No checkpoint found with id <id>." List .retrospect/checkpoints/ if it exists.
4. The checkpoint file contains: { "id", "created_at", "mode", "step", "state", "pending_reflections" }.
5. Resume execution at step inside the mode identified by mode (e.g., if mode: "apply" and step: 2, jump to Step 2 of modes/apply-mode.md).
6. Restore any pending_reflections into the working context before resuming.

---

Quick Mode (when $ARGUMENTS is empty)

Fast, focused, selective. Gather context → identify what's actually signal → propose where each learning belongs.

Step 1 — Gather what happened

Read what exists, skip what doesn't:

• .retrospect/session-summary.json — hook-captured session summary
• .retrospect/events.log — raw trigger events
• .retrospect/reflections.json — prior reflections (confidence ≥ 0.7)
• git diff HEAD~3..HEAD --stat — recent file changes

Step 1b — Map the instruction landscape

Before routing any learning, understand which instruction files exist in this repo and for this user. This determines where a learning should land — the right target is as important as the content.

Harness	What to detect
Claude Code	CLAUDE.md at project root, .claude/CLAUDE.md, ~/.claude/CLAUDE.md (global)
Claude Code skills	find . -name SKILL.md — skills active in this workspace
Claude Code hooks	find . -name hooks.json — what events are wired
Claude Code memory	~/.claude/projects/*/memory/ — auto-memory files
Cursor	.cursorrules, .cursor/rules/*.mdc
Windsurf	.windsurfrules, .windsurf/rules/
GitHub Copilot	.github/copilot-instructions.md
Devin	DEVIN.md, .devin/
OpenHands	.openhands_instructions
Aider	.aider.conf.yml, CONVENTIONS.md

Why this matters:

• A learning may need to land in multiple harness files if the repo uses more than one
• If the same rule already exists in another harness's file, skip or note the cross-reference
• If harness files conflict (Cursor says X, CLAUDE.md says opposite) — that's a signal worth surfacing even if the user didn't ask

Step 2 — Find the signal

Not every session has learnings worth capturing. Look for:

• Trigger phrases in events.log: "you forgot", "always", "never", "I told you", "keep doing this"
• Files touched repeatedly across sessions that correlate with corrections
• Prior reflections that were never acted on
• Patterns that feel like they've happened before

If nothing stands out — say so. Don't manufacture learnings to fill the output.

Step 2b — Check for skill candidates

While scanning for signal, also watch for patterns that warrant a new or updated skill — not just a memory entry or CLAUDE.md rule. A skill candidate is a repeatable workflow with 2+ steps that a user manually executes across sessions. Ask yourself:

• Did the same multi-step sequence appear twice or more in the session or reflections?
• Is there a workflow the user had to describe or re-explain?
• Is there a correction that implies a missing skill (e.g., "next time, first do X, then Y, then Z")?

For each candidate, immediately assess its scope:

• User-scope — useful across repos and projects, installs globally at ~/.claude/skills/<name>/SKILL.md
• Repo-scope — specific to this codebase, installs at .claude/skills/<name>/SKILL.md in the repo

If you find at least one candidate, surface it in the output as a dedicated ### Skill Suggestions section (see Step 4). Do not bury it in the improvements table — it is a different category of recommendation.

Step 3 — Apply the core principle

For each signal, ask: how general is this? Then call mcp__retrospect__reflect and mcp__retrospect__route_learning to structure and route it.

Step 4 — Present findings

Keep it tight. One short sentence per observation. Confidence matters — show it:

## Retrospect: [date]

### Signals
- [what was observed and why it's signal, not noise]

### Proposed Improvements
| Target | Change | Confidence | Why |
|--------|--------|-----------|-----|
| CLAUDE.md | Add: "..." | 88% | Appeared 3× this session |
| repo-memory | Store: "..." | 74% | Correction from user, first time |

### Skill Suggestions
> Only present this section if at least one candidate was found in Step 2b. Omit entirely if none.

**[skill-name]** · [user-scope | repo-scope]
Trigger: "[the phrase or situation that would invoke this]"
Evidence: [N occurrences — what you saw]
Install path: [~/.claude/skills/<name>/SKILL.md | .claude/skills/<name>/SKILL.md]
Run `/retrospect --evolve` to generate a full proposal with preview.

### Next Steps
[/retrospect --apply] to write the ≥85% ones.
[/retrospect --evolve] if skill suggestions were found above.
[/retrospect --deep] if you want a full architecture audit.
Nothing significant found? That's fine — a clean session is good news.

---

Safety Rules

In all modes:

• Never overwrite CLAUDE.md or any skill without showing the proposed change first
• Never apply below 70% confidence without explicit user request
• Always explain why, not just what — reasoning prevents stale rules
• Never delete memory entries — mark superseded ones instead
• Append to .retrospect/reflections.json, never overwrite it