How-to Prompting

Debug a prompt that isn't working

A prompt that used to work, and now does not, is not a mystery, it is a bug with a findable cause. This is a six-step checklist for finding it: reproduce the failure enough times to know if it is consistent or random, read what you actually wrote instead of what you meant, check whether the model had the facts and format it needed, strip the prompt down until the failure moves, apply the smallest fix that closes the gap, then verify it against the original case and a few others before you trust it.

6 steps12 min readLast verified August 2026

What you’ll learn

Tell a genuinely broken prompt from a merely random one, by running it two or three times before touching anything.
Spot the gap between the words you actually typed and the request that was in your head.
Check whether the model actually had the facts, labels, or format spec it needed before it started generating.
Strip a failing prompt down to the smallest version that still breaks, to find the exact trigger.
Apply the smallest fix that closes the gap, instead of rewriting the whole prompt from scratch.
Verify a fix against the original failure and a few other real inputs before trusting it.

A prompt that used to work, and now does not, is not a mystery. It is a bug, and bugs have a findable cause. The instinct when a prompt goes wrong is to rewrite the whole thing from scratch, or bolt on more adjectives ("be more careful," "really make sure this time") and hope. Neither is a debugging process, and neither tells you what was actually broken. This is a six-step checklist for finding the real cause: reproduce the failure enough times to know if it is consistent or random, read what you actually wrote instead of what you meant, check whether the model had the facts and format it needed, strip the prompt down until the failure moves, apply the smallest fix that closes the gap, then verify it against the original case and a few others before you trust it.

New to this? A setting called temperature controls how much randomness a model mixes into which word it picks next. Low temperature sticks to the safest, most likely choice almost every time; higher temperature lets it take a less likely path now and then. That one setting is why running the exact same prompt twice can return two different answers, which is exactly what step 1 below checks for.

Six symptoms, and where to start

Symptom	Likely cause	Fix
Answer changes on every run	Sampling randomness, not a broken prompt	Lower temperature, or add a format constraint that narrows the plausible answers
Wrong format (prose instead of a list, etc.)	Format request buried at the end, or never stated exactly	State the exact format up front, before the content request
Missing a specific fact or number	The fact lived in your head, not in the prompt	Paste the source data or fact in directly, do not reference it by name
Off-tone or wrong audience	No audience or role named	Name the audience, or add a role instruction
Repeats a quirk from your one example	A single few-shot example taught an accident	Add a second, different example so the pattern generalizes
Works on short inputs, breaks on long ones	Instructions buried far from the relevant content	Move the key instruction closer to the content, or repeat it at the end

The reasoning behind each row is in the six steps below.

Work the six steps in order the first time something breaks; after a few passes you will jump straight to the right one.

1. Reproduce it: run the same prompt two or three times

Before touching the prompt, run it again exactly as it is, two or three times, on the same input. Say you have a support-ticket triage prompt that used to return a clean urgency label, and it just started returning something different almost every run: "high," then "urgent," then "P1." Running it three times right away tells you something the first bad answer alone cannot: is this the same failure every time, or a different flavor of wrong on each run?

Fails the same way every time: the prompt itself has a real gap. Move to step 2.
Fails a different way on each run, but every answer is individually reasonable: partly a sampling artifact. Try a lower temperature or a tighter format constraint before assuming the prompt is broken.
Fails by consistently missing the same piece of information: not noise. Something the model needed was never in the prompt at all. Move to step 3.

Do not expect a temperature of zero to make this fully deterministic either. Even at 0.0, Anthropic's own Messages API documentation notes the results will not be fully deterministic,² so a small amount of run-to-run variation is normal and not automatically a bug.

2. Read what you actually wrote, not what you meant

The single most common bug is not a missing capability of the model. It is the gap between the words you typed and the request sitting in your head. You know the ticket needs to route into exactly three buckets; the prompt just says "decide how urgent this ticket is" and stops there.

The prompt you wrote, next to what you actually meant

What the prompt says:
Decide how urgent this ticket is.

What you actually meant:
Decide how urgent this ticket is, and answer with exactly one of
three words this system already routes on: low, medium, or high.
Nothing else, no explanation.

Closing that gap is not cleverness, it is a reading exercise. Anthropic's own prompting guidance puts it plainly: show your prompt to a colleague with minimal context on the task and ask them to follow it; if they would be confused, the model will be too.¹ Read your prompt cold, as if you had never seen the task before, and every place you hesitate is a place the model was probably guessing too.

3. Check the context: did the model have what it needed

A model does not know what it was not told. If it is missing a fact, a document, an exact label set, or a format spec, it does not leave a blank, it fills the gap with whatever is typical for that kind of request and keeps going, confidently, in the wrong direction. Check these before assuming the instruction wording is the problem.

Facts and data: is the source text actually pasted into the prompt, or referenced by name only ("that report," "the ticket above") with nothing attached?
The exact label set or schema: if there are only three valid answers, does the prompt say so, or does it just describe the task and hope?
Examples: if the shape is easier to show than describe, is there at least one worked example in the prompt?
Constraints and edge cases: does the prompt say what to do with an input that does not clearly fit any category?

4. Isolate by simplifying: strip until the failure moves

Once you suspect where the gap is, prove it by cutting the prompt down, not by guessing. Remove or simplify one part at a time, rerun on the exact input that was failing, and watch what changes.

1CutRemove or simplify one part of the prompt: a sentence, an example, a persona.

2Re-runRun the trimmed prompt on the exact input that was failing.

3CompareDoes the same failure still happen?

4BranchStill fails: cut again. Now works: put that part back, it was not the cause, and cut something else instead.

The isolate loop

Keep going until you cannot remove anything else without the prompt starting to work. What is left is the minimal failing case, and the bug is almost always visible in it once the surrounding noise is gone.

Trimming a real prompt down to its minimal failing case

Full prompt (fails on some runs):
You are a support triage assistant for a SaaS company. Read the
ticket below, weigh the customer's plan tier and how long they
have been a customer, and be thoughtful and thorough about how
urgent this really is.

Ticket: "My export button has been broken for two days and I have
a board meeting tomorrow."


Minimal version (still fails the same way):
Decide how urgent this ticket is.

Ticket: "My export button has been broken for two days and I have
a board meeting tomorrow."

The plan-tier detail, the persona, and the "be thoughtful" flourish were not the problem: the minimal two-line version fails exactly the same way. That rules them out and points straight back at what step 3 already flagged: the label set was never stated.

5. Apply the smallest fix

With a minimal failing case in hand, the fix is usually small: a clearer instruction, one added example, an explicit format constraint, or moving the format request to the front of the prompt instead of the end. Resist rewriting the whole prompt from scratch. A full rewrite changes five things at once, so if the new version works you still do not know which change actually did it.

The smallest fix: one closed set of labels, stated up front

Before (still failing):
Decide how urgent this ticket is.

Ticket: "My export button has been broken for two days and I have
a board meeting tomorrow."


After:
Decide how urgent this ticket is. Reply with exactly one of these
three words: low, medium, high. No other text.

Ticket: "My export button has been broken for two days and I have
a board meeting tomorrow."

Notice the constraint sits before the ticket, not after it. Anthropic's prompting guidance is direct about being specific about the desired output format and constraints;¹ stating it first means every token the model writes afterward is already conditioned on "pick one of three words," not fighting a paragraph of reasoning it already started.

6. Verify: the failing case, plus a few others

A fix aimed at one failing case can quietly break a case that used to work. Before you trust it, run it wider than the single input that started this.

Rerun the exact input that started this, more than once if step 1 showed any randomness. Confirm it now answers the same, correct way every time.
Rerun two or three other real inputs the prompt already handled well. Confirm none of them got worse.
Rerun one deliberately awkward input: an empty case, a genuinely ambiguous one, an outlier. See if the fix holds up or was too narrow.
If anything regressed, the fix was tied to a symptom of the minimal failing case instead of its real cause. Go back to step 4 and isolate again.

Key idea

Reproduce before you diagnose. Isolate before you fix. Verify past the one case that started the investigation. Almost every "the prompt is broken" problem is a specific, findable gap between what you wrote and what the model needed, not a limit of the model itself.

Going further: a fixed bug does not stay fixed on its own. Save the input that started this, two or three inputs that already worked, and one edge case as a small, permanent eval set: five to eight real inputs with the answer you expect from each. Rerun the whole set every time you touch the prompt again, not just the case that prompted the change. That is what catches a fix in one place quietly breaking something you got right before.

Read next: How to prompt better, and why it works explains why steps 2, 3, and 5 work at the level of next-token prediction, the same mechanism this checklist keeps pointing back to. Prompt patterns for real tasks has copy-paste templates for the fix once you know what is missing: format constraints, few-shot examples, and more.

Sources

Verified against primary sources: August 2026.

Prompting best practices. Anthropic, Claude Docs. https://platform.claude.com/docs/en/build-with-claude/prompt-engineering/claude-prompting-best-practices
Messages API reference. Anthropic, Claude Docs. https://platform.claude.com/docs/en/api/messages

All How-tos