oliver-kriska/phx:learn-from-fix

Learn From Fix

After fixing a bug or receiving a correction, capture the lesson to prevent future mistakes.

Usage

/phx:learn-from-fix Fixed N+1 query in user listing - was missing preload
/phx:learn-from-fix String vs atom key mismatch in params handling
/phx:learn-from-fix LiveView assign_async needs render_async in tests

Workflow

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 ${CLAUDE_SKILL_DIR}/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]

Iron Laws

1. NEVER edit plugin files — files under ~/.claude/plugins/ are cached and overwritten on updates
2. DO NOT duplicate existing lessons — always check CLAUDE.md and memory before writing
3. Capture the root cause, not the symptom — "missing preload" not "query was slow"

References (READ-ONLY — do NOT edit)

• ${CLAUDE_SKILL_DIR}/references/common-mistakes.md — Common Elixir mistakes reference. Consult when checking for duplicates. Ships with the plugin — NEVER modify.