Learn From Fix
After fixing a bug or receiving a correction, capture the lesson to prevent future mistakes.
Usage
/phx:learn Fixed N+1 query in user listing - was missing preload
/phx:learn String vs atom key mismatch in params handling
/phx:learn LiveView assign_async needs render_async in testsWorkflow
Step 1: Identify the Pattern
Look at recent conversation context. Ask yourself:
- What was the root cause? (not the symptom)
- Is this a common mistake others might make?
- Can it be prevented with a simple rule?
Step 2: Check Existing Knowledge
Check if already documented:
- Grep project CLAUDE.md for the pattern keyword
- Check auto-memory files for similar lessons
- Read
references/common-mistakes.md(READ-ONLY plugin reference — do NOT edit this file)
If already documented, tell the user and stop.
Step 3: Decide Where to Save
CRITICAL: NEVER edit plugin files. Files under ~/.claude/plugins/ are cached and get overwritten on updates. Always write to project or memory locations.
| Scope | Write to | Example |
|---|---|---|
| This project only | Project CLAUDE.md | "Never use raw SQL in this app" |
| All Elixir projects | Auto-memory MEMORY.md | "jsonb always uses string keys" |
| Detailed fix with context | .claude/solutions/ via /phx:compound | Complex debugging story |
Step 4: Write the Lesson
For project CLAUDE.md — append a concise rule:
### [Category] Iron Laws (continued)
N. **[SHORT RULE NAME]** — Do NOT [bad pattern]. Instead [good pattern]For auto-memory — append to ~/.claude/projects/{project-hash}/memory/MEMORY.md:
### Lesson: [Title]
- **Pattern**: Do NOT [bad] — instead [good]
- **Why**: [root cause explanation]Step 5: Consider Broader Updates
If the lesson is significant enough to be an Iron Law:
- Suggest adding to project CLAUDE.md Iron Laws section
- If it's universal (applies to all Elixir projects), suggest updating the plugin itself (the user can PR it)
Output
After capturing, confirm:
Lesson captured in [location]
Pattern: Do NOT [bad pattern] — instead [good pattern]
Category: [Ecto/LiveView/OTP/Testing/etc]References (READ-ONLY — do NOT edit)
references/common-mistakes.md— Common Elixir mistakes reference. Consult when checking for duplicates. Ships with the plugin — NEVER modify.