Learn From Failure

# /learn-from-failure — Convert failure to reusable artifact

When a failure occurs, classify it, check for repetition, and produce a durable artifact that prevents recurrence.

## Trigger

`/learn-from-failure` or `/learn-from-failure <failure description>`

Caddy auto-surfaces on: "same issue", "happened again", "recurring", "third time", "keeps happening"

## Flow

### 1. Identify failure
- If argument provided: use it
- If no argument: ask "What failed?"

### 2. Classify failure mode

| Mode | Description | Example |
|------|-------------|---------|
| `routing` | Task sent to wrong agent/model/tool | Opus used for a read-only task |
| `verification` | Output accepted without checking data flow | Video "looked fine" but spec was wrong |
| `tool` | Tool unavailable, broken API, wrong usage | Gmail MCP auth expired |
| `knowledge` | Agent lacked domain knowledge | Didn't know SDK v6 changed type strings |
| `authority` | Agent acted outside delegation zone | the AIgent made a Level 3 decision |

### 3. Check for repetition
Read `$AIGENT_VAULT/memory/FAILURE_MODES.md`. Search for Pattern lines matching the current failure's root cause.

- **0-1 prior occurrences:** Phase 1 — log and monitor
- **2+ occurrences:** Phase 2 — mandatory artifact. A log entry is not enough.
- **3+ occurrences:** The prior artifact failed. Diagnose why and fix or replace it.

### 4. Log to FAILURE_MODES.md
Append a new entry following the existing format:

```markdown
## {YYYY-MM-DD} — {short symptom name}

**Symptom:** {what went wrong, user-visible}
**Verified cause:** {exact mechanism}
**Fix:** {what was done}
**Layer:** {which system layer}
**Pattern:** {one-line category — this is the load-bearing piece for repetition detection}
```

### 5. Determine artifact type

| Failure mode | Artifact | Target |
|---|---|---|
| `routing` | Caddy trigger or hook | `.claude/hooks/` or `.claude/skill-index.json` |
| `verification` | Checklist item in doctrine | Relevant doctrine note |
| `tool` | SKILL_GAPS entry + skill spec | `memory/SKILL_GAPS.md` |
| `knowledge` | Vault note or memory candidate | `concepts/` or `memory/` |
| `authority` | Flag to the operator | `aigent_authority_matrix.md` |

### 6. Create artifact
- For routing: draft a Caddy enrollment entry with 3+ trigger phrases
- For verification: append a concrete, runnable check to the relevant doctrine
- For tool: log to SKILL_GAPS.md, suggest /skill-hunt if external capability needed
- For knowledge: write a memory candidate or vault note
- For authority: surface to the operator with recommendation

### 7. Output
```
Failure logged: {classification}
Pattern: {pattern line}
Repeated: {yes/no, count}
Artifact: {type} at {path}
```

## Boundary

Per [[Self-Learning Doctrine]]: a failure logged without an artifact is a false resolution. The ledger grows, the failure recurs, the system learns nothing.

## Related

- [[concepts/Self-Learning Doctrine]] — the doctrine this skill implements
- [[memory/FAILURE_MODES.md]] — the ledger
- [[concepts/Capability Expansion Doctrine]] — tool failures feed the expansion loop
- [[Self-Improving CLAUDE.md]] — the broader self-improvement cycle