Use after any mistake, correction, or unexpected outcome to capture the most generalizable version of the learning. Also use when reviewing docs/lessons.md for cleanup.
Turn specific mistakes into general principles. Put them where they'll actually prevent the next mistake.
docs/lessons.md for entries that should be promoted or prunedDon't record what happened. Record why it happened.
| Level | Example | Quality |
|---|---|---|
| Symptom | "Don't use displayio.Group with too many items" | Bad — too specific |
| Mechanism |
| "ESP32-S3 RAM is limited — budget display objects carefully" |
| Better |
| Principle | "Know your resource constraints before building" | Best |
CLAUDE.md ← Rules that govern ALL behavior (rare — only after 2+ occurrences)
↑ promote
Skill files ← Patterns specific to a workflow
↑ promote
docs/lessons.md ← General principles not yet promoted (staging area)
↑ capture
Memory system ← User preferences, project context (not engineering lessons)
Format: One sentence stating the rule, then a Test or Why.
Good:
Know your resource constraints before building. Test: if you can't state the RAM budget, network timeout, and power draw for your target device, you haven't done enough research.
Bad:
The MatrixPortal S3 ESP32-S3 ran out of memory when I created 15 displayio.Group objects with bitmap fonts in code.py because the heap is only 256KB.
Rules:
Before adding:
docs/lessons.md — similar lesson already exists? Update it.After adding or promoting:
Keep docs/lessons.md under 20 entries.