# Reflect And Improve

> 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.

- Skill: `aroyburman-codes/reflect-and-improve` (Agent Skill)
- Install (CLI): `npx skillmds@latest add aroyburman-codes/reflect-and-improve`
- Raw SKILL.md: https://api.skillmd.com/api/skills/aroyburman-codes/reflect-and-improve/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: aroyburman-codes (https://skillmd.com/u/aroyburman-codes)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/aroyburman-codes/reflect-and-improve

---


# 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:**
```markdown
# 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:**
```markdown
# 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.