---
name: learn-from-mistakes
description: Use when a session ends or user invokes /learn-from-mistakes
---

# Learn From Mistakes

Extracts agent mistakes from current session. Writes learned rules into the specialized skills/agents responsible for that domain. Self-trains project agents to avoid repeating mistakes.

---

## When to Invoke

- User types `/learn-from-mistakes`
- `wrap-up` skill calls this at session end
- After a session with visible corrections, retries, or failures

**Scope limit:** Only analyzes current context window. Compacted/archived history is inaccessible — state this if user asks why old mistakes aren't captured.

---

## Step 1: Read Project CLAUDE.md

Read the project's `CLAUDE.md` to extract:
- Which specialized skills exist + their file path ownership (e.g. `src/components/ui/**` → `md-ui-developer`)
- Which local agents exist under `.claude/agents/`

This is the ground truth for eligible targets. Only skills/agents listed in CLAUDE.md are writable. Generic global skills (`plan`, `brainstorm`, `ship`, `debug`, `tdd`, `verification-before-completion`, etc.) are **read-only — never write learned rules to them**.

---

## Step 2: Collect Mistake Signals

Scan transcript for:

**User corrections:**
- "no", "don't", "wrong", "revert", "that's not right", "never", "stop"

**Agent failures:**
- Same file edited 2+ times in session
- Build / type / test failure → agent fix → success
- User explicitly names what went wrong

**Filter — only count as mistake if ALSO:**
- Followed by an actual edit/fix, OR
- A build/type/test actually failed, OR
- User cited a specific rule or convention

User changing their mind mid-session = NOT a mistake. Skip unless above criteria met.

Cross-ref git diff: changed file matches correction signal → mistake. Changed file matches only user's stated feature request → intentional, skip.

---

## Step 3: Classify Each Mistake

Per mistake, record:

```
file: <path>
signal: <what triggered it>
wrong: <what agent did>
correct: <what should have happened>
```

---

## Step 4: Resolve Target Skill/Agent

Match mistake's file path against CLAUDE.md skill registry → find responsible skill/agent.

No match → log as unresolved, suggest creating new skill/agent and registering it in CLAUDE.md.

---

## Step 5: Check for Meta-Failure

Before writing a rule, read the target skill's hand-written body.

If proposed rule **restates something already written** in the skill → **meta-failure**: agent failed to load or follow the skill, not a missing rule.

Log as: `meta-failure: skill <name> not loaded/followed` — do NOT add the rule.

---

## Step 6: Dedup Check

Read full `## Learned Rules` section of target file.

Semantically compare proposed rule against all existing entries — judgment, not grep. "Does any existing rule already cover this behavior?"

- Covered → skip insert, increment `fired:N` on matching entry
- Not covered → proceed

---

## Step 7: Write Rule

Append to `## Learned Rules` section (create at file bottom if missing).

**Format — caveman, max 2 lines:**

```markdown
### {slug} | fired:1 | {YYYY-MM-DD}
{wrong behavior} → wrong. {correct behavior}. {file/context if relevant}.
```

**Quality gates:**
- States wrong behavior + correct behavior
- Actionable — no vague rules ("be careful with X")
- Max 2 lines
- Terse — read under context pressure

**Example:**
```markdown
### spacing-token-raw-number | fired:1 | 2026-04-20
`gap={4}` → wrong. SpacingKey = design-token string. Use `gap="md"`.

### rtl-icon-no-mirror | fired:2 | 2026-04-20
Directional icons need `<Icon mirror />`. Never CSS transform for RTL flip.
```

---

## Step 8: Report

```
## Learning Report

### Mistakes Found: N

| # | Mistake | Signal | Target | Rule Slug |
|---|---------|--------|--------|-----------|
| 1 | SpacingKey raw number | type error | md-ui-developer | spacing-token-raw-number |
| 2 | ... | user: "never" | md-server-dev | ... |

### Changes Made
- Rules added: N
- Rules updated (fired count++): N
- Meta-failures (skill not loaded): N
- Unresolved (no target): N

### Unresolved
- <mistake> → no skill covers `src/X/**` — consider creating `md-X` skill, register in CLAUDE.md
```