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
   • 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:

## Lessons

Before starting any task, scan this table for relevant lessons. Read the full file when a trigger matches what you're about to do.

| Consult when | Lesson |
|--------------|--------|
| Creating a new Expo project | [2025-01-10-expo-project-setup.md](lessons/2025-01-10-expo-project-setup.md) |

When adding a new lesson, append a row with:

• Consult when: Activity-based trigger describing when to read this (e.g., "Creating or upgrading an Expo project", "Setting up JWT authentication")
• Lesson: Relative link to the dated lesson file

Tips for Good Lessons

• Lead with the right approach: The lesson should read like advice for someone starting fresh, not a debugging post-mortem
• Be specific: "Use npx create-expo-app" is better than "use the official scaffolding tool"
• Name the anti-pattern explicitly: Future Claude needs to recognize when it's about to do the wrong thing
• Keep explanations brief: Just enough context to understand why the right approach is right
• One lesson per file: Keep each lesson focused on a single insight
• Write activity-based triggers: Frame "Consult when" around what Claude is about to do, not what error it might see