learn-from-failure
Convert failures into reusable artifacts and check repetition. Use when analyzing a failure mode or a recurring failure.
SKILL.mdskills/learn-from-failure/SKILL.md
GitHub/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>
Use 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:
## {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 |
Skill description or hook | the skill's SKILL.md description, or .claude/hooks/ |
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: add 3+ trigger phrases to the skill's
description("Use when ...") - 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.
Bounded procedure experiment (fixture only)
A Finding is an observation, not a verified cause or authority to edit a procedure. The fixture mechanics use a declarative grammar and a pinned historical corpus. Freeze the candidate, evidence, corpus, size budgets and rollback before evaluating. Require a passing verdict and a caller-supplied approval bound to the candidate and base. Distinct identity strings are not authenticated review. This proves mechanics on a fixture, not natural-language procedure compliance or live behavior.
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