Before You Fix It, Name It — Agent Failures Come in Four Recognizable Shapes

The agent returns something wrong. You look at it for a few seconds, then do the reflex everyone does: you start fixing. Fix the output. No luck. Rewrite the prompt. Still off. Add one more instruction. The third time around, you realize you've been flailing for half a morning and never once stopped to ask: how is this thing actually broken?

That's the trap. You aren't short on effort — you have too much of it, poured into the wrong spot. You're treating the symptom without ever making the diagnosis.

01Each kind of break has its own shape — and you can learn to spot it

A good doctor doesn't write a prescription the moment the patient says "it hurts." They ask: where, what kind, when. Because that one word hurts points to ten different illnesses, and each one wants a different treatment.

Agent failures are the same. "It's wrong" is the cry of pain — useless for treatment. But how it goes wrong is not endless. After enough faceplants, you'll see it always lands in one of four shapes: it fabricates something that isn't there to look like it did the work; it gets stuck in a loop while still looking busy; it reports done and stops, but the result is quietly wrong; or it hands you a wrong output with no error line pointing at the break. Four shapes, four distinct symptoms — visible enough to name on sight.

Notice: three questions separate all four. Is there a real footprint? Did it stop? Did it report anything? Answer those three and you've already pinned the kind — before fixing a single line.

02Why these four repeat, not ten random ones

These four aren't a tidy grouping I invented. They repeat because they spring from the same nature: an agent is a thing that guesses the most likely next part, with none of the physiological discomfort a human feels when handed something beyond them. Missing that brake, it slides along four natural directions.

When it lacks a tool or a permission, the most likely direction is to build something that looks done — the faking shape. When the task is vague and every small step looks reasonable, it keeps going without noticing it's circling — the stuck shape. When it believes it has finished, it declares done with the same confidence it uses when it's right — the silent miss shape. And when an early assumption goes off, that drift flows downstream all the way to the final output without making a sound — the needs-locating shape. Four directions of slide, four shapes. Grasp this shared root and you stop being surprised: next time you see a failure, you don't ask "what weird thing happened," you ask "of the four familiar directions, which one is this?"

03Once it's named, each name has its own exit

With the diagnosis done, the rest is light: each kind has a probe to confirm it and its own exit — and crucially, they differ. Treating one kind with another kind's method is exactly why you flailed for half a morning.

All four probes are short, and all four do one job: force the agent — or force you — to surface the fact a quick glance hides. Diagnosing right is half the cure.

You don't need to memorize the cure for each kind today — the four pieces are there for when you want to go deep. What you do need is the act of stopping: before you touch a key to fix it, ask "which of the four shapes is this?" One question, a few seconds. But it's the fork that decides whether you fix the real thing or flail for half a morning.

Every break has a name. Next time the agent returns something wrong, don't rush to cure it — name it first. Once you've named it right, the road shows itself.