Skip to content
AI Engineer Guide.

concept · coding · intermediate · concept 28 of 30

Failure modes

0 of 30 complete

Why it matters

Agent runs fail in repetitive ways, and each repetition costs a full session plus a review. Without a taxonomy, teams respond to the last failure they saw and the same class returns under a different task. Naming the failure at its first wrong decision, and writing a detector for it, converts an anecdote into something the harness can catch before a human spends time on it.

Mental model

It is a crash taxonomy for a vehicle: same road, different parts fail. The metaphor breaks because these failures are correlated, since bad discovery produces a bad patch and then bad verification, so the first symptom is rarely the cause.

How it works

Four stages, one wrong decisionInteractive
14 nodes · 5 branches
root causerootnoteruled out or rejected

Step 1 of 7

Collect traces, not stories

Each failing run arrives with its trace. A retelling already contains a theory about the cause, and the theory is what the grouping is supposed to test.

root · current

Failed run · first wrong decision

A failing run with its trace. The unit of analysis is the earliest decision that was wrong, because the last symptom is usually a consequence.

Root of the hierarchy

Step 1/7 · Collect traces, not stories

Figure. Failing runs sorted by the first wrong decision, not by the last symptom: discovery, edit, verification and reporting, each with the detector that fires without a human reading the transcript. The crossed branch is the symptom cut — 'the answer was wrong' — which merges the other four into one bucket that no fix can act on.

What to notice. The four stages and the three named failure modes — fabricated API, wrong-file edit, weakened test — are the page's; the finer causes under each stage are authored instances of them, and no counts are drawn because the page publishes no sample. The grouping is a classification, not a flow: a bad discovery often produces a bad patch, but that correlation is not drawn as an edge, because a tree would imply the later failure nests inside the earlier one. Omitted: detection thresholds and the volume at which trace review stops paying.

Text version

A failure taxonomy drawn as a hierarchy. The root is a failed run, grouped by its first wrong decision. Four sibling stages hang from it. Discovery is detected from the trace and holds editing a similar module and never opening the failing test. Edit is detected from the diff and a typecheck and holds a fabricated API and a weakened test. Verification is detected by running the suite against the base and holds running a subset and reporting green, and accepting a flaky pass. Reporting is detected by comparing the claim with the trace and holds saying done without running the check. A rejected branch, grouping by symptom, is drawn crossed and ruled out because it puts all four stages into one bucket. A regression-set note keeps one reproduction task per group after the fix.

  1. Collect failing runs with their traces rather than anecdotes, and group them by the first wrong decision.
  2. Separate discovery failures from edit, verification and reporting failures.
  3. Write a detector for each group: a log field, a diff check or a test assertion.
  4. Fix the earliest failure in the chain first, because later ones are often consequences.
  5. Re-run the grouped tasks after the harness change and compare group counts.
  6. Keep a regression set of tasks that failed once and now pass.

Trade-offs

ChoiceGood forCostFails when
Prompt-level fixesFast to tryDo not generalise, hard to verifyFailure recurs across tasks
Harness-level checksDetectable and testableEngineering effortFailure is rare and cheap
Blocking on any anomalySafetyFalse stopsAgent needs exploratory freedom
Post-hoc trace reviewRich diagnosisSlow, sampling onlyVolume is high
Trade-off mapInteractive

Good for

Fast to try

Cost

Do not generalise, hard to verify

Fails when

Failure recurs across tasks

  1. Failure recurs across tasks
  2. Failure is rare and cheap
  3. Agent needs exploratory freedom
  4. Volume is high

Figure. Each choice with what it buys, what it costs, and the case where it loses.

What to notice. The fourth column is the decision: if the losing case describes your situation, the choice is wrong.

Text version

Four trade-offs: Prompt-level fixes is good for Fast to try, costs Do not generalise, hard to verify, and fails when Failure recurs across tasks. Harness-level checks is good for Detectable and testable, costs Engineering effort, and fails when Failure is rare and cheap. Blocking on any anomaly is good for Safety, costs False stops, and fails when Agent needs exploratory freedom. Post-hoc trace review is good for Rich diagnosis, costs Slow, sampling only, and fails when Volume is high

Failure modes

  • Fabricated API. The agent calls a method that does not exist and the code never compiles. Debug: run the type checker and grep the diff for symbols absent from the dependency's exported types.
  • Wrong-file edit. The change lands in a similar module and no test covers it. Debug: check whether the edited file appears in the discovery trace for the reported symptom.
  • Test weakening. Assertions are removed until the suite is green. Debug: diff test files and count removed assertions per patch.

In production

Aggregate failures by category per release and alert when a category rises. Keep one reproduction task per category in the regression suite.

Common misconceptions

People think: Failures are random model noise.

Actually: They cluster by task shape and harness gap, which makes them fixable.

People think: A passing suite means the run succeeded.

Actually: It means the assertions held, and weakened tests are a documented failure mode.

Interview angle

Group failures by the first wrong decision and name a detector for each. A strong answer fixes the earliest failure in the chain and keeps a reproduction task per category. Listing model weaknesses in the abstract, with no detection or reproduction, is the weak answer.

Sources