Learning Log

Core Principles

1. Log insights, not rules — MEMORY.md stores corrective rules ("always use X instead of Y"). The learning log stores discoveries ("X behaves differently when Y is configured because Z"). Rules prescribe behavior; insights explain the world.

2. Structure enables searchability — Every entry has a date, category, title, description, and affected files. Consistent structure means you can search by category, scan titles, or find entries related to specific files.

3. Log during work, not after — Capture insights the moment they occur. Waiting until the end of a session means half the detail is lost. A 2-line entry written immediately is worth more than a paragraph reconstructed from memory.

4. Periodic review extracts patterns — A monthly scan of the learning log reveals recurring themes. Three "gotcha" entries about the same subsystem suggests a systemic issue worth addressing. Individual entries are useful; patterns across entries are actionable.

5. Distinct from handoff notes — The wrap-up-ritual handoff captures session state (done/pending/learned). The learning log is a persistent, growing knowledge base. Handoffs are overwritten; the log only grows (and is periodically pruned).

Patterns

Log Entry Format

Each entry follows a consistent structure in .claude/learning-log.md: