reflect

# Reflect

Analyze the current conversation to extract lessons from mistakes or corrections, then persist them as "if we were starting over" guidance for future sessions.

## Workflow

1. **Identify the problem**: Scan the conversation for where things went wrong - look for user corrections, error messages, failed attempts, or "actually, do X instead" moments

2. **Trace the resolution**: Follow the back-and-forth to understand how the issue was resolved - what did the user clarify? What fix worked?

3. **Draft the lesson**: Extract what you think the actionable insight is - frame it as "if we were starting over, here's the right approach"

4. **Validate with user**: Present your draft lesson and ask the user to confirm or correct it. This is critical because:
   - You may have misidentified the root cause (correlation vs causation)
   - Some "fixes" may have been red herrings that happened to work alongside the real fix
   - The user knows which insight is actually valuable to persist

   Ask something like: "Here's the lesson I extracted - is this the right takeaway, or did I miss the actual root cause?"

5. **Write and register**: Once validated:
   - Suggest filename `YYYY-MM-DD-<topic>.md` and confirm with user
   - Save to `~/.claude/lessons/` using the format in [lesson-template.md](references/lesson-template.md)
   - Add entry to Lessons table in `~/.claude/CLAUDE.md` (create table if needed - see format below)

## Edge Cases

- **No clear mistake**: If the user wants to capture a learning that wasn't from a mistake (e.g., "remember this approach"), still use the same format but frame "What to avoid" as the less-optimal alternative
- **Multiple lessons**: If multiple unrelated lessons emerge from one conversation, write them as separate files and validate each one individually with the user

## CLAUDE.md Format

Add a Lessons section to `~/.claude/CLAUDE.md` with a flat table mapping activities to lesson files:

```markdown
## Lessons

Before starting any ta