learn-from-fix git:20260321.4e9d9e9A

Immutable. This exact content is served forever at /api/v1/blob/38f4f019cafcadc7.

---
name: phx:learn
description: Capture lessons learned after fixing a bug or receiving a correction from the user. Use whenever the user corrects your approach, points out a mistake, or teaches you a project-specific pattern. Updates knowledge base to prevent future mistakes.
effort: low
argument-hint: <description of what was fixed>
---

# 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 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:

```markdown
### [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`:

```markdown
### 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:

```text
Lesson captured in [location]

Pattern: Do NOT [bad pattern] — instead [good pattern]
Category: [Ecto/LiveView/OTP/Testing/etc]
```

## 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.