---
name: reflection
description: This skill should be used when the user says "reflection", "reflect on the changes", "reflect on this session", or asks to capture lessons learned from the current conversation.
disable-model-invocation: true
---
# Reflection
The goal is to identify lessons from this session that should be permanently captured in CLAUDE.md — so future sessions benefit without repeating the same mistakes, clarifications, or decisions.
Review the **entire conversation history** — every message, correction, and preference — as the primary source. Code diffs are supplementary.
## Current Git State (supplementary context)
- Branch: !`git branch --show-current`
- Changes since last commit: !`git diff --stat HEAD`
- Staged changes: !`git diff --stat --cached`
## Process
1. **Read the full conversation from top to bottom.** Pay attention to:
- Questions the user had to answer that should have been obvious from CLAUDE.md
- Corrections the user made to your approach or output
- Preferences or constraints the user stated (even casually)
- Things you got wrong on the first attempt and had to revise
- Decisions made about architecture, naming, tooling, or workflow
- Anything the user explicitly said to always/never do
2. **Review the diffs** (supplementary) — Read modified files for context on what was built and why, but do not let this overshadow lessons from the conversation itself.
3. **Identify lessons** in these categories:
- **Patterns & conventions** — Things that worked well and should be encoded as rules
- **Gotchas & pitfalls** — Things that caused confusion, required retries, or were non-obvious
- **Architecture decisions** — Choices made that future sessions should know about
- **Workflow & communication preferences** — How the user prefers to work, communicate, or receive output
- **Outdated/wrong memory** — Anything in CLAUDE.md or MEMORY.md that turned out to be incorrect or missing
4. **Read the current CLAUDE.md** to avoid duplicating what's already there and to find gaps.
5. **Propose edits to CLAUDE.md** — For each lesson worth keeping, suggest the specific text to add, change, or remove, and where it belongs.
6. **If no lessons are found**, explicitly state: "No CLAUDE.md updates needed from this session." This confirms the session was considered.
7. **Do not apply edits automatically.** Present proposals to the user and wait for approval.
8. **After applying approved edits**, print a brief summary in chat of what changed.
## Output Format
**When lessons are found:**
```
## Reflection
### [Category]
**Lesson**: <what was learned>
**Proposed CLAUDE.md change**: <exact text, with target section>
---
(one block per lesson)
```
**When no lessons are found:**
```
## Reflection
No CLAUDE.md updates needed from this session. The following were considered but already covered or not worth persisting:
- <item> — already in CLAUDE.md / too session-specific / etc.
```
**After applying approved changes:**
```
## CLAUDE.md updated
- Added: "<description>" under ## Section
- Modified: "<what changed>" in ## Section
- Removed: "<what was removed>"
```
