Why prompts fail

build-with-llms lesson 2 made the case that an instruction can lose to everything else in the box. 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 guesswork. There are three failure causes, they look different, and you can tell them apart in about two minutes.

1Three causes, and they need different fixes

Every prompt failure is one of these.

Most people reach straight for the third. "The model can't do this" is a comfortable conclusion — it ends the debugging. It is also wrong most of the time, because the first cause is enormously more common and looks exactly like incompetence from the outside.

Ambiguity hides in ordinary words. Every one of these 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. Which date — invoiced, due, paid? In what format? What if there are three?
• Recent tickets. Recent as in seven days, thirty, or since the last release?
• Fix the tone. Fix it towards what? Warmer, shorter, more formal, less apologetic?
• List the key points. How many is key? Ranked or in document order?

You know what you meant. The prompt does not contain what you meant. That gap is where almost all of this lives.

2Debug in that order

Check ambiguity first because it is the cheapest to test and the most likely to be the answer.

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()

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

resp = client.messages.create(
    model="claude-sonnet-5",
    max_tokens=300,
    temperature=0,
    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?"
        ),
    }],
)
print(resp.content[0].text)

Answer 3 is the one you want. Every item it lists is a decision you left to a coin flip, and answer 2 tells you which side the coin landed on this time. If the restatement is wrong, stop debugging — you have found it. Write the missing decisions into the prompt and try again.

Step two: shrink the input. If the restatement is right but the answer is still wrong, cut the context down 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 and task last, clear delimiters around the data, and less pasted context rather than more.

Step three: only now, believe it is hard. A task that fails on a tiny clean input, at temperature 0, with an accurate restatement, is a task the model cannot do as posed. That is a real category — exact arithmetic on long numbers, anything needing information the model does not have, anything with five interacting sub-tasks. The fix is not a better sentence. It is decomposition (lesson 4), 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".

3Why "be careful" does nothing

Now the sentences everyone adds and nobody measures. This is very important. Be thorough. Take your time. Please be accurate. Double-check your work.

They read as pressure. The model does not experience pressure. It predicts the next token given everything in the box, and "this is very important" does not change what output is being described — so there is nothing for it to do differently. Compare that with "quote the sentence you took each value from", which changes the output concretely, on every run.

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

Two honest notes, because this area is thick with folklore.

Role prompting is a habit, not a proven accuracy lever. "You are an expert X" reliably changes vocabulary, register and how technical the answer gets, and that is genuinely useful when you care how it sounds. Claims that it makes the model right more often are weak and depend heavily on the task. Use it for tone. Do not use it instead of specifying the output.

"Take your time" is not the same as chain-of-thought. Asking for step-by-step reasoning does work, for a mechanical reason covered in lesson 5 — the model gets more tokens to compute in. "Take your time" produces no extra tokens, so it produces no extra computation. The phrasing is similar; the effect is not.

The next lesson goes at placement — which half of the request your instruction should live in, and why that changes how much weight it carries.