Failure Catalog

Agent failures are not random. The same seventeen patterns show up across codebases, tools, and teams — because they follow from how LLMs resolve ambiguity, optimize for local coherence, and report confidence without skin in the game. Learn to recognize the pattern early and you save the week of thrash that comes from treating each incident as unique.

This catalog is diagnostic, not theatrical. Pick the symptom that matches what you are seeing, open the deep page, run the recovery prompt, and update the repo so the next session cannot repeat it.

Recovery loop

The expensive mistake is skipping the Memory step: you fix the code once and leave the unwritten rule in your head. The next agent will violate it again. See Docs as Memory and Recovering From Bad Output.

The seventeen modes

#	Failure mode	Deep page
1	Shallow demo instead of real system	Shallow Implementation
2	Implements the easiest version, not the required one	Shallow Implementation
3	Mixes product assumptions into implementation	Shallow Implementation
4	Ignores existing architecture	Architecture Erosion
5	Duplicates logic	Architecture Erosion
6	Adds unnecessary abstractions	Architecture Erosion
7	Inconsistent naming	Architecture Erosion
8	Documentation no longer matches code	Architecture Erosion
9	Changes unrelated files	Scope and Context Failures
10	Overfits to the latest instruction	Scope and Context Failures
11	Forgets previous constraints	Scope and Context Failures
12	Breaks hidden flows	Scope and Context Failures
13	Removes important edge cases	Scope and Context Failures
14	Hallucinates APIs	Hallucination and False Confidence
15	Silently weakens security	Hallucination and False Confidence
16	Tests that only test mocks	Hallucination and False Confidence
17	Stuck loops, thrash, and fix-time scope creep	Stuck Loops and Thrash

Mode 17 is one catalog entry with three operational faces (loop, thrash, silent creep) — they share a recovery shape: cut the session, re-ground in artifacts, restart narrow. The deep page treats each face separately.

How to use this section mid-incident

1. Match the symptom column on the deep page — do not start a new agent chat yet.
2. If the session is already looping, /clear or new session before any recovery prompt (context hierarchy).
3. Run the recovery prompt; demand evidence, not reassurance.
4. Land the prevention artifact (spec line, CLAUDE.md invariant, gate, test) in the same PR or the next one.
5. Independent review before merge — builder context is contaminated by definition.

Related

• Why Agents Fail — the mechanisms behind this catalog.
• Shallow Implementation — demo-quality and median-product defaults.
• Architecture Erosion — consistency death by a thousand sessions.
• Scope and Context Failures — drift, amnesia, and collateral damage.
• Hallucination and False Confidence — invented APIs, soft security, mock theaters.
• Stuck Loops and Thrash — when to kill the session.
• Recovering From Bad Output — full recovery playbook.