Diagnosing prompt, hallucination and model issues

Start from evidence, not from the complaint

A complaint says “the bot gave a wrong answer”. That is a symptom. Diagnosis means finding which part of the system produced it, and the transcript is where you look. Anthropic's engineers repeat one piece of advice more than any other: read the transcripts. They record exactly what the model was given, what it did, and what it returned.

1. Reproduce. Capture the exact input, system prompt, retrieved context, tools, model and parameters. A bug you cannot replay you cannot fix.
2. Check the plumbing first. Did the response end because of max_tokens? Did your code read the wrong content block? Was a tool result empty or an error? These look like model failures and aren't.
3. Ask whether the answer was available. Search the context for the fact the model needed. Present, absent, or contradictory?
4. Isolate one variable. Re-run the same case with a clarified prompt, then with a stronger model or higher effort. Whichever change fixes it tells you the category.
5. Fix, and add the case to the eval set so the regression suite catches it next time (4.2).

CONFIGS = {
    "baseline":       dict(model="claude-haiku-4-5", system=PROMPT_V1),
    "clearer_prompt": dict(model="claude-haiku-4-5", system=PROMPT_V2),
    "stronger_model": dict(model="claude-sonnet-5",  system=PROMPT_V1),
}

for name, cfg in CONFIGS.items():
    passed = 0
    for case in failing_cases:                     # from logs or the eval set
        r = client.messages.create(max_tokens=2048,
                                   messages=case.messages, **cfg)
        if r.stop_reason == "max_tokens":          # plumbing, not intelligence
            print(name, case.id, "TRUNCATED")
            continue
        text = "".join(b.text for b in r.content if b.type == "text")
        passed += grade(case, text)                # code or rubric grader
    print(f"{name}: {passed}/{len(failing_cases)}")
# Clearer prompt fixes it  -> prompt failure
# Only stronger model does -> model mismatch
# Neither                  -> look at the data or retrieval

Prompt failure

A prompt failure is when the model could do the task but was not told clearly enough what the task was. Typical signs: the right content in the wrong format; an instruction followed on some inputs and ignored on others; a sensible answer to a different question; behaviour that changed after a model upgrade because the prompt was tuned to the old model's habits.

Anthropic's prompting guide gives the diagnostic test in one line: show the prompt to a colleague with minimal context and ask them to follow it — if they'd be confused, Claude will be too. Its fixes map to the common causes: be explicit about the output and constraints; give the reason behind an instruction so the model can generalise; add three to five relevant, diverse examples; separate instructions, context and inputs with XML tags; and for long documents, put the documents at the top and the question at the end.

You are a support agent.
Answer the customer's question
about returns. Be concise.
{{POLICY}}
{{QUESTION}}

<policy>{{POLICY}}</policy>
<question>{{QUESTION}}</question>

Answer from <policy> only.
Customers read this on a phone,
so use at most 3 sentences.
If the policy doesn't cover it,
say so and offer a human agent.
Quote the policy line you used.

Hallucination

A hallucination is output that is factually wrong or unsupported by the context the model was given — an invented policy clause, a citation to a case that doesn't exist, a confident number with no source. The first diagnostic question is simple: was the correct fact in the context?

Anthropic's guide to reducing hallucinations lists these techniques. The basic ones: explicitly allow Claude to say it doesn't know; for long documents (over about 20k tokens), extract word-for-word quotes before doing the task; and have Claude cite a quote for each claim, retracting any claim it can't support. The advanced ones: step-by-step reasoning before the answer, best-of-N comparison, iterative refinement, and restricting the model to the documents provided. The same page is honest about the limit — these reduce hallucinations but don't eliminate them, so critical information still needs validating.

Model mismatch

Model mismatch runs in both directions. Under-powered: the prompt is clear and the context complete, but the task needs more reasoning than the model delivers — multi-step analysis collapses, long agentic tasks lose the thread. Over-powered: a simple, high-volume classification runs on the most capable model, so latency and cost miss their targets while accuracy has nothing left to gain. Both are mismatches between task and model; only one shows up as wrong answers.

Anthropic's model-selection guide frames it as a balance of capabilities, speed and cost, and offers two starting strategies: start efficiency-first with a fast, cheap model and upgrade only for specific capability gaps, or start capability-first and optimise down. Either way, the decision should come from your own eval set run across models — the guide calls a good evaluation set the most important step. It also notes that the effort parameter trades intelligence for latency and cost within a single model and is often a better lever than switching models.

One more category deserves a name because it is so often misdiagnosed: harness and configuration bugs. A response cut off at max_tokens looks like the model stopping mid-thought. After a migration, code that reads content[0].text can pick up a thinking block instead of the answer, and requests carrying non-default temperature can fail outright on newer models. None of these is a prompt, hallucination or model problem, and none is fixed by changing one.

Traps the wrong answers are built from

You should now be able to

• Classify a failure as prompt failure, hallucination, model mismatch or harness bug from transcript evidence.
• Isolate a cause by varying one factor — prompt, model, effort, context — on the failing cases.
• Apply Anthropic's hallucination-reduction techniques and know their limits.
• Recognise under-powered and over-powered model mismatches and choose between upgrade, effort change and routing.
• Turn every diagnosed failure into a regression test.