Agent Failure Pattern Manager

The Problem

Yesterday you spent 20 minutes correcting your agent's import paths. Today it uses the wrong imports again. Last week it declared "done" without running tests — you corrected it, it agreed, and this morning it declared "done" without running tests again. The intelligence gained during each session evaporates when the session ends. You're paying for the same mistakes on repeat.

What You Get

• Structured LEARNINGS.md system — a running retrospective file that captures what went wrong, root cause analysis, and concrete prevention rules for every repeated mistake
• 13-pattern failure taxonomy — categorizes agent failures into Tier 1 (Architectural: mega-prompt, invisible state, error cascade), Tier 2 (Execution: tool bloat, hallucinated arguments, schema drift), and Tier 3 (Data/Context: stale context, instruction drift, over-confident completion, scope creep)
• Detect → Diagnose → Document workflow — structured process for turning corrections into permanent learning entries with dates, root causes, anti-pattern names, and actionable prevention rules
• Session start active recall — agent reads LEARNINGS.md at session start, surfaces the top 3 relevant entries, and explicitly acknowledges which prevention rules it's applying
• Consolidation protocol — periodic merging of duplicate entries, removal of outdated patterns, and promotion of cross-cutting patterns into Consolidated Principles
• CLAUDE.md integration — prevention rules that prove stable through consolidation get promoted from LEARNINGS.md (session knowledge) to CLAUDE.md (permanent project rules)

Why This Beats Prompting It Yourself

"Remember this mistake" is an instruction agents can't fulfill — they have no mechanism to persist learning across sessions without structured files. This skill creates the infrastructure (LEARNINGS.md + session protocol + consolidation rules) that turns verbal corrections into permanent behavioral changes. Without it, every correction is a one-time event that evaporates when the session ends.

Example Session

You: "You used the wrong import path again — I told you last time it's from app.models.user import User"

Agent: "You're right, I apologize. Recording this learning:

[2026-07-15] Used wrong import path for User model

• What happened: Agent wrote from models import User instead of from app.models.user import User
• Root cause: Stale Context Injection (AP-9) — assumed standard import pattern instead of checking project structure
• Prevention: Before writing any import for a project-specific class, search for the class definition first to verify the actual module path

Prevention rule saved. At the start of my next session, I'll read this entry and apply it before writing any imports."

Use Cases

• Developers who use coding agents daily and find themselves repeating the same corrections
• Teams onboarding AI agents to existing codebases with specific conventions and gotchas
• Solo developers who want their agent to accumulate project-specific knowledge over time
• Anyone who has said "I already told you not to do that yesterday"
• Major refactors or feature work where early-session mistakes compound across multiple sessions

Known Limitations

Not every correction is a pattern worth recording — one-off typos and self-corrected mistakes generate noise. Aim for 1-3 quality entries per session, not a dump of every interaction. LEARNINGS.md requires periodic consolidation (monthly or at ~100 entries) or it becomes a dumping ground the agent can't effectively search. Prevention rules must be concrete actions, not vague directives — "before doing X, always do Y" works; "don't do X" doesn't.