Why prompts fail

An instruction can lose to everything else in the box — the pasted document, the examples, the conversation so far. This lesson is what to do when yours has. Debugging a prompt feels like guesswork because most people change three things at once and keep whichever version looked better on one example. It does not have to be. There are three failure causes, they look different, and you can tell them apart in about two minutes.

1.Three causes, and they need different fixes

Most people reach straight for the third. "The model can't do this" is comfortable — it ends the debugging. It is also usually wrong, because the first cause is far more common and looks exactly like incompetence.

Ambiguity hides in ordinary words. Each is a decision you did not make, so the model made it for you:

• Summarise this. One sentence or one page? For whom? Keeping the numbers or not?
• Extract the date. Invoiced, due, or paid? In what format? What if there are three?
• Recent tickets. Seven days, thirty, or since the last release?

You know what you meant. The prompt does not contain it. Anthropic's prompting guide offers a free first check: hand the prompt to a colleague with none of your context. Wherever they would stop and ask, the model is guessing.

2.Debug in that order

Check ambiguity first: it is the cheapest to test and the most likely.

Step one: make it restate the task. Before asking for the work, ask what it thinks the work is.

from anthropic import Anthropic

client = Anthropic()
MODEL = "claude-sonnet-5-5"   # as of October 2026

def text_of(resp) -> str:
    return "".join(b.text for b in resp.content if b.type == "text")

TASK = "Summarise the support ticket for the on-call engineer."

resp = client.messages.create(
    model=MODEL,
    max_tokens=2000,   # thinking is on by default and counts against this
    messages=[{
        "role": "user",
        "content": (
            f"{TASK}\n\n"
            "Do not do the task yet. Answer three things first:\n"
            "1. What am I asking you to produce?\n"
            "2. What will the output look like - fields, length, format?\n"
            "3. What in my instruction could be read more than one way?"
        ),
    }],
)
if resp.stop_reason != "end_turn":
    raise RuntimeError(f"no usable answer: {resp.stop_reason}")
print(text_of(resp))

This sample was not run here, so try it on your SDK version first.

Expect an answer shaped like this invented one: a few sentences of prose, and under question three, what it would be guessing — whether to name the customer, whether the engineer wants symptoms or cause, how long "short" is. Those are coins you left in the air. Write the decisions down: Two lines. Line one: what the customer sees. Line two: what to check first. No names. The summary was never the problem.

If the restatement is wrong, you have found it. It is evidence, not proof, since it is the model's own account of its reading; confirm by changing the prompt and re-running.

Step two: shrink the input. If the restatement is right but the answer is wrong, cut the context to one small, clean example and re-run. If it now works, the problem was never capability. Your instruction was buried, and the fix is placement: document first, task last, clear delimiters, less pasted context. Research on older models (Liu et al., 2023) found the middle of a long input gets used worst.

Step three: only now, believe it is hard. A task that fails the same way on a tiny clean input, with an accurate restatement, is one the model cannot do as posed — exact arithmetic on long numbers, information it does not have, five interacting sub-tasks. The fix is decomposition (Decomposition), a tool, or code.

Prove the first two before you believe the third. "The model can't do this" is usually "I did not say what I wanted".

Two causes can hide inside "hard", both from Anthropic's Sonnet 5.5 guide and vendor-reported (as of October 2026). A JSON-only answer at low effort can skip the thinking and miss on multi-step tasks. And the model sometimes answers from memory when the facts may have changed, instead of looking. Both are settings, not capability; Steering how much it thinks covers them.

When not to use the ladder. If you have twenty real cases with expected answers, skip the detective work and run them. A rate beats a hunch, and one restatement cannot see a failure that shows up one run in ten. That is Versioning and testing prompts.

3.Why "be careful" does nothing

Now the sentences everyone adds and nobody measures. This is very important. Be thorough. Take your time. Double-check your work. They read as pressure. The model does not feel pressure; it predicts the next token from everything in the box, and "this is very important" does not change what output is being described.

The rule: if an instruction does not change what the output contains, it does not change the output.

Emphasis can also do harm. Anthropic's guide reports that on Opus 4.5 and 4.6, prompts that shouted to fix an ignored rule began to over-trigger once the models followed system prompts more closely; the fix was plain wording (as of October 2026). A bare "never" has the same flaw: with no reason attached, the model has to guess where the rule stops. The guide's example is a ban on ellipses, rewritten to say a speech engine will read the text aloud and cannot pronounce them. With the reason, the model can handle cases you never listed.

"Don't" rules pull hard and can collide with other instructions. A Claude Code team member said in a July 2026 conversation that a rule true nine times in ten misfired on the tenth (an anecdote, no published numbers). For each rule, ask where it is wrong, then write that case down.

Two honest notes.

Role prompting is a habit, not a proven accuracy lever. "You are an expert X" reliably shifts vocabulary and register, which is useful when you care how it sounds. Claims that it makes the model right more often are thin and task-dependent. Use it for tone, never instead of specifying the output.

"Take your time" is not step-by-step reasoning. Step-by-step prompting does work, for the mechanical reason in Thinking out loud, but the evidence is narrower than the folklore. A June 2025 Wharton study of older models on one hard science benchmark found a clear gain only against a baseline that forbade thinking, little against the model's default, and a small, mixed gain on reasoning models. Whether it holds today is untested.

Next: placement — which half of the request your instruction should live in, and why that changes how much weight it carries.