name: learn description: "End-of-session reflection and knowledge capture. Summarizes the session, identifies key learnings, and updates CLAUDE.md. Triggers: 'learn', 'remember this', 'update claude.md', 'save this', end of productive session."

Learn Skill

Capture what matters before context dies. Update CLAUDE.md for future sessions.

Quick Flow

1. Reflect: What happened? What was discovered?
2. Filter: Is this worth remembering? (See criteria below)
3. Read: Check existing CLAUDE.md to avoid duplicates
4. Propose: Tell user what you plan to add
5. Write: Update CLAUDE.md after confirmation

What's Worth Capturing

Yes:

• Non-obvious architecture ("routes are in ApiRouter.java, not controllers")
• User preferences ("prefers early returns over nested ifs")
• Gotchas discovered ("silently fails without REDIS_URL")
• Build/test quirks ("needs Docker running")
• Decisions & rationale ("chose X over Y because...")

No:

• Generic knowledge Claude already has
• One-off fixes
• Temporary workarounds
• Obvious things

Rule: Would future-you be glad to know this, or is it noise?

CLAUDE.md Structure

# CLAUDE.md

## Project Overview
[What this is, one paragraph]

## Architecture  
[Key decisions, component relationships]

## Development
[Build/test commands, common workflows]

## Code Style & Preferences
[User's preferences]

## Gotchas
[Things that'll bite you]

## Session Log
[Recent learnings, dated, newest first]

Writing Style

Write like notes to a coworker:

• Concise: One line if possible
• Specific: ./gradlew bootRun not "run gradle"
• Honest: Note if something's a workaround

# Good
- `thunder-auth` silently fails if REDIS_URL unset. No error, just no session cache.

# Bad  
- Be careful with auth module configuration.

Session Log Hygiene

• Date entries (newest first)
• After ~20 entries, consolidate old ones into permanent sections
• Remove entries that became obsolete
• Move repeated patterns into Architecture/Gotchas sections

## Session Log

### 2025-01-31
- Hot-reload only works for `game-logic` module, not core
- Added WebSocket reconnection test (was missing)

### 2025-01-28
- Moved to MkDocs (simpler than Sphinx)

Handling Conflicts

If new info contradicts existing CLAUDE.md:

1. Point out the conflict to user
2. Ask which is correct
3. Update with corrected info + date
4. Note in session log: "Corrected: X was wrong, actually Y"

Output

End with:

1. What you added (brief)
2. The actual changes
3. "Want me to adjust anything?"