reflect-and-improve

name	reflect-and-improve
description	Use after completing significant work, recovering from errors, or at session breakpoints to review actions, synthesize learnings, and write persistent improvements to memory files. Reduces repeated mistakes and user friction over time.

Reflect and Improve

A self-improvement loop for Claude Code. After significant work, this skill reviews what happened — errors made, corrections received, implicit preferences — and writes confirmed learnings to persistent memory files. Future sessions start smarter.

When to Invoke

• After completing multi-file edits, project setup, or debugging sessions
• After making an error and recovering from it
• At natural session breakpoints (switching tasks, wrapping up)
• After a tool call is denied and you adjusted approach
• When explicitly requested

The Reflection Framework

Run these 6 steps in order. Skip any step with no findings.

1. Review Checkpoint

Scan recent actions 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
• Approaches 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

If 0 signals found, skip to step 6.

2. Permission Patterns

Track which operations the user approved or denied.

Write to: permissions.md in the project memory directory

Format:

# Permission Patterns
Last updated: YYYY-MM-DD

## Approved
- git commit — always approved
- npm install — approved for this project

## 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 2+ times OR explicitly stated
• Never persist tokens, passwords, or secrets
• Update existing entries, don't append duplicates

3. Error Catalog

Classify errors and record the fix.

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
- Prevention: Before writing Python code, check version requirements

Rules:

• Only log errors likely to recur
• Include the prevention step — that's the value
• After 30 days with no recurrence, consider archiving

4. User Preference Signals

Capture implicit preferences revealed through behavior and corrections.

Signal types:

• Coding style: tabs vs spaces, quotes, naming conventions
• Communication style: prefers short answers, likes/dislikes emojis
• Tool choices: package manager, test framework, linter
• Workflow patterns: commits frequently vs batches, reviews diffs vs trusts agent

Write to: preferences.md in the project memory directory

Rules:

• Only record preferences confirmed by 2+ instances or explicit statement
• Don't duplicate what's already in CLAUDE.md or project config
• Project config wins over inferred preferences

5. Memory Synthesis

Write confirmed learnings to persistent memory files.

What qualifies:

• Pattern observed 2+ times this session
• Explicit user instruction ("always do X", "never do Y")
• Error with a clear prevention rule
• Stable permission pattern

What doesn't qualify:

• Speculation or single observations
• Anything already in project docs
• Session-specific context
• Sensitive data

Process:

1. Check if a relevant topic file exists (permissions.md, errors.md, preferences.md)
2. If yes: update existing entries, add new ones, remove outdated ones
3. If no: create the topic file
4. Update MEMORY.md if it needs a link to a new topic file (keep under 200 lines)

6. Friction Audit

Identify moments where the experience could be smoother.

Look for:

• User had to repeat themselves
• User had to correct a misunderstanding
• User provided context that should have been known
• A task took multiple rounds when one would suffice

Output format:

## Friction Audit — [date]
- User corrected package manager twice -> saved to preferences.md
- Had to re-read config file I should have cached -> read it first next time

For each friction point, identify if there's a systemic fix and apply it.

Memory File Hygiene

• Every entry gets a "last updated" date
• During reflection, flag entries older than 90 days for review
• If a preference contradicts recent behavior, update or remove it
• Each topic file: aim for under 100 lines
• MEMORY.md: must stay under 200 lines
• Archive old entries when files grow too large

Key Principles

1. Less is more. A few high-quality entries beat a bloated log.
2. Edit, don't append. Keep files clean by updating existing entries.
3. Confirm before persisting. Save observed facts, not assumptions.
4. Privacy first. Never persist secrets, tokens, or personal data.
5. Respect existing docs. Don't duplicate CLAUDE.md or project config.