The Four Failure Modes

When an agent produces bad output, the bug is almost never the model. Classify which of four layers failed before you change anything.

Why this, for you: the reflex when an agent goes wrong is to reword the prompt or swap the model. Usually wrong. This lesson gives you a diagnostic sequence — see what the agent saw, then what it was told, could do, and whether the tier fit — so you fix the actual cause instead of poking at symptoms. Pure daily-coding payoff.

Code bugs have stack traces. Agent bugs have context windows. When an agent fails, the problem is usually not the model — it's what the model was given. Four modes account for nearly all of it.

1 Classify before you change

Mode	What went wrong
Missing context	The agent never had the information it needed
Conflicting instructions	Two directives contradicted each other
Missing/blocked tools	The agent couldn't act and worked around the gap
Capability ceiling	The task exceeded the model tier's capability

Determine which category applies before changing anything. Rewording a prompt to fix a missing-tool problem just produces a new confidently-wrong answer — you treated the symptom, not the layer.

2 The diagnostic sequence

Walk the layers in order — each step answers a different question about what the agent experienced.

1. What did it SEE? # /memory — which CLAUDE.md & rules loaded? 2. What was it TOLD? # scan loaded files for contradictions 3. What could it DO? # which tools were enabled vs blocked? 4. Was the TIER right?# context/tools fine but still wrong → escalate

A subtle one lives in step 1: when Claude Code compacts a long session, path-scoped rules and nested CLAUDE.md files drop from context until a matching file is read again. An agent that followed a rule early may stop later — not because it ignored the rule, but because the rule fell out. Check session length before blaming the model.

3 Reproduce to split structural from session-specific

Start a fresh session, give exactly the same inputs, watch for the same bad output.

What the reproduction tells you

Recurs → the problem is structural: instructions, skills, or tool config. Doesn't recur → it was session-specific: context drift, overflow, or transient state. Transcripts under ~/.claude/projects/ let you trace when behavior diverged and whether a tool failure caused the pivot.

A worked example: an agent keeps writing *.spec.ts when the project wants *.test.ts. /memory shows the project CLAUDE.md says *.test.ts but a stale user-level CLAUDE.md says *.spec.ts — both loaded. Project scope wins, but the user-level entry is noise. Remove it; reproduce in a fresh session; fixed. Root cause was a scope conflict, not the model or the prompt.

When the diagnostic is overkill

The sequence assumes a structural failure. Skip it for transient errors (rate limits, timeouts — just retry in a fresh session), for genuine capability gaps (no context tuning fixes a task beyond every tier), and for over-instrumented setups (when dense CLAUDE.md layers are the problem, reducing instruction surface area beats per-failure diagnosis).

↪ Your win: fix the layer, not the symptom

Classify into one of four modes — missing context, conflict, missing tool, capability — first.
Walk see → told → do → tier in order with /memory and the session transcript.
Remember compaction drops rules; a rule that held early can quietly fall out later.
Reproduce in a fresh session to separate structural bugs from session-specific drift.
Skip the sequence for transient errors, true capability gaps, and over-instrumented harnesses.

Retrieval practice — recall, don't peek

Question 1When an agent produces bad output, the cause is usually…

Question 2An agent that followed a rule early but stops later may have hit…

Question 3Reproducing in a fresh session separates…

Question 4You should reach step 4 (model tier) only after…

Question 5 · spaced recall from Lesson 03Under ESAA, "fail-closed" validation means a malformed event…

Ask me anything. Want the full symptom→cause table (rule ignored, confident-but-wrong, longer path than needed), or how /doctor surfaces config issues invisible during normal runs? Next in Part 3: Stopping the Bleeding — loop detection and circuit breakers.