Reflect and Improve
Overview
A self-improvement loop for Claude Code. After significant work, this skill triggers a structured review of what happened — errors made, permissions granted, user corrections, implicit preferences — and writes confirmed learnings to persistent memory files so future sessions start smarter.
Goal: Every session leaves Claude Code slightly better calibrated to the user and codebase.
When to Invoke
- After completing multi-file edits, project setup, or debugging sessions
- After making an error and recovering from it
- When the user explicitly runs
/reflect-and-adapt - At natural session breakpoints (switching tasks, wrapping up)
- After a tool call is denied and you had to adjust approach
The Reflection Framework
Run these 6 steps in order. Skip any step that has no findings.
1. Review Checkpoint
Scan recent actions in the current session for signals worth learning from.
Look for:
- Tool calls that failed or were retried
- User corrections ("no, I meant...", "not that file", "use X instead")
- Permission denials (user clicked "deny" on a tool call)
- Approaches that were abandoned mid-way
- Tasks that required multiple attempts
Output format:
## Review Checkpoint — [date]
- [RETRY] Ran tests 3 times before realizing venv wasn't activated
- [CORRECTION] User said "use pnpm, not npm" — package manager preference
- [DENIED] User denied `git push` — wants to review before pushing
- [ABANDONED] Started editing wrong file, had to switch to correct one
Action: If you find 0 signals, skip to step 6. Don't force findings.
2. Permission Patterns
Track which operations the user approved or denied to reduce future permission prompts.
Capture:
- Operations the user said "yes" to (especially repeated ones)
- Operations the user denied (and why, if stated)
- Implicit permissions (user asked you to do X, so Y is clearly fine too)
Write to: permissions.md in the project memory directory
Format:
# Permission Patterns
Last updated: YYYY-MM-DD
## Approved
- git commit with co-author — always approved
- npm install — approved for this project
- file creation in src/ — approved
## Denied
- git push — user wants to review first
- modifying .env — never touch without asking
## Implicit
- if user asks to "set up tests", creating test files is implicitly approved
Rules:
- Only record permissions observed across 2+ instances OR explicitly stated by user
- Never persist token values, passwords, or secrets
- Update existing entries rather than appending duplicates
3. Error Catalog
Classify errors you made and record the fix so you don't repeat them.
Error categories:
| Category | Example |
|---|---|
| Wrong assumption | Assumed Python 3.10 but project uses 3.8 |
| Missing context | Didn't read package.json before running npm commands |
| Tool misuse | Used cat instead of Read tool |
| Wrong file | Edited the test file instead of the source file |
| Stale knowledge | Used deprecated API method |
| Ordering error | Ran tests before installing dependencies |
Write to: errors.md in the project memory directory
Format:
# Error Catalog
Last updated: YYYY-MM-DD
## [date] Wrong assumption — Python version
- What happened: Used match/case syntax, but project requires Python 3.8
- Root cause: Didn't check pyproject.toml before writing code
- Fix: Always read pyproject.toml or setup.cfg for Python version constraints
- Prevention: Before writing Python code, check version requirements
## [date] Missing context — Package manager
- What happened: Ran `npm install` but project uses pnpm
- Root cause: Didn't check for pnpm-lock.yaml
- Fix: Check for lock files (pnpm-lock.yaml, yarn.lock, package-lock.json) first
- Prevention: Before any install command, check which lock file exists
Rules:
- Only log errors that are likely to recur (not one-off typos)
- Include the prevention step — that's the real value
- After 30 days with no recurrence, consider archiving old entries
4. User Preference Signals
Capture implicit preferences the user reveals through their behavior and corrections.
Signal types:
- Coding style: tabs vs spaces, single vs double quotes, semicolons, naming conventions
- Communication style: prefers short answers, wants explanations, likes/dislikes emojis
- Tool choices: preferred package manager, test framework, linter, editor
- Workflow patterns: commits frequently vs batches, reviews diffs vs trusts agent
- Architecture preferences: monorepo vs multi-repo, OOP vs functional, etc.
Write to: preferences.md in the project memory directory
Format:
# User Preferences
Last updated: YYYY-MM-DD
## Coding Style
- TypeScript: single quotes, no semicolons, 2-space indent
- Python: black formatter, type hints preferred
- Prefers functional style over classes
## Communication
- Likes concise responses — no fluff
- Doesn't want time estimates
- Prefers bullet points over paragraphs
## Tools
- Package manager: pnpm
- Test framework: vitest (not jest)
- Linter: biome
## Workflow
- Wants to review git diffs before committing
- Prefers small, focused commits over large batches
Rules:
- Only record preferences confirmed by user behavior (2+ instances) or explicit statement
- Don't record preferences that are already in CLAUDE.md or project config files
- If a preference contradicts project config (e.g., .prettierrc), project config wins
5. Memory Synthesis
Write confirmed learnings to persistent memory files. This is the actual "getting smarter" step.
Target directory: The project-level memory directory
- For project-scoped learnings:
~/.claude/projects/<project>/memory/ - For global learnings:
~/.claude/memory/(but be conservative — most things are project-scoped)
What qualifies as a confirmed learning:
- Pattern observed 2+ times in this session
- Explicit user instruction ("always do X", "never do Y")
- Error that was fixed and has a clear prevention rule
- Permission pattern that's clearly stable (not a one-off)
What does NOT qualify:
- Speculation or single observations
- Anything already in CLAUDE.md or project docs
- Session-specific context (current task, temporary state)
- Sensitive data (tokens, passwords, personal details)
Process:
- Check if a relevant topic file already exists (permissions.md, errors.md, preferences.md)
- If yes: use Edit tool to update existing entries, add new ones, remove outdated ones
- If no: create the topic file with clear structure
- If MEMORY.md needs a link to a new topic file, add it (keep MEMORY.md under 200 lines)
Anti-patterns to avoid:
- Append-only logging (leads to bloat — edit and consolidate instead)
- Saving everything (only save what changes future behavior)
- Duplicating project docs (if it's in .eslintrc, don't also put it in preferences.md)
6. Friction Audit
Identify moments where the user experience could be smoother.
Look for:
- User had to repeat themselves (said the same thing twice)
- User had to correct a misunderstanding
- User had to provide context that should have been known
- A task took multiple rounds when it could have been done in one
- User seemed frustrated or impatient
Output format:
## Friction Audit — [date]
- User corrected package manager twice → saved to preferences.md
- Had to re-read config file I should have cached → added to review checklist
- User provided project structure context that exists in README → read README first next time
Actions:
- For each friction point, identify if there's a systemic fix (memory update, workflow change)
- If the fix is a memory update, do it now (step 5)
- If the fix requires a workflow change, note it but don't over-engineer
Memory File Hygiene
Staleness Prevention
- Every entry should have a "last confirmed" or "last updated" date
- During reflection, scan for entries older than 90 days — flag for review
- If a preference has been contradicted by recent behavior, update or remove it
Size Limits
- Each topic file: aim for under 100 lines
- MEMORY.md: must stay under 200 lines
- If a file grows too large, archive old/low-value entries
File Organization
~/.claude/projects/<project>/memory/
MEMORY.md # Index + high-level context (loaded into system prompt)
permissions.md # Approved/denied operations
errors.md # Error catalog with prevention rules
preferences.md # User style and tool preferences
Example: Full Reflection Output
=== Reflect and Improve — 2026-02-17 ===
## Review Checkpoint
- [CORRECTION] User said "use vitest not jest" — test framework preference
- [RETRY] Failed to run tests — forgot to install deps first
- [DENIED] git push denied — user reviews before pushing
## Permission Patterns
→ Updated permissions.md: added "git push — review first"
## Error Catalog
→ Updated errors.md: "Always run install before test commands"
## User Preferences
→ Updated preferences.md: "Test framework: vitest (not jest)"
## Memory Synthesis
→ Wrote 3 entries across 3 topic files
→ No MEMORY.md changes needed (topic files already linked)
## Friction Audit
- 1 friction point: had to be told test framework twice
→ Fixed: saved to preferences.md, won't happen again
Important Principles
- Less is more. A few high-quality memory entries beat a bloated log.
- Edit, don't append. Keep files clean by updating existing entries.
- Confirm before persisting. Don't save assumptions — save observed facts.
- Privacy first. Never persist secrets, tokens, or personal data.
- Respect existing docs. Don't duplicate what's in CLAUDE.md or project config.
- Date everything. Every entry needs a timestamp for staleness tracking.