How to debug a prompt that gives bad output

A systematic method for diagnosing why a prompt fails and fixing it without trial and error.

The most common failure modes

Missing goal: you described the task but not what success looks like — the model guesses the acceptance criteria.
Ambiguous scope: 'brief' means 50 words to you and 500 to the model. Specify numbers.
Missing context: the model lacks the constraints, definitions, or background that make the task unambiguous in your head.
Wrong format: you want a table, the model gives prose. You want JSON, the model adds markdown fences.
Conflicting instructions: 'be concise' plus 'cover everything' in the same prompt produce averaged-out garbage.
No anchor for missing info: when the model doesn't know something, it fills the gap. Telling it to flag gaps prevents hallucinations.

The debugging process

Step 1 — isolate the symptom: write down exactly what went wrong. 'Too long', 'wrong format', 'hallucinated facts', 'missed the point', 'inconsistent across runs'.
Step 2 — find the missing instruction: for each symptom, ask 'what would I need to say to a capable human to prevent this?' That missing instruction is what goes into the prompt.
Step 3 — add one fix at a time: change a single variable per run so you know what actually fixed it. Multiple changes at once make it impossible to know which one worked.
Step 4 — test with edge cases: run the fixed prompt on a harder version of the task, a short input, a long input, and an input with missing data. Real prompts need to handle all of these.
Step 5 — lock what works with a format example: once the output is right, add a one-line example of the exact format you want. It prevents drift when you reuse the prompt.

Templates

Prompt self-diagnostic

You are a prompt quality reviewer. Analyze the following prompt and identify the top 3 reasons it might produce bad output.

For each issue:
1. Name the failure mode (e.g., "missing format constraint", "ambiguous scope", "no anchor for missing info").
2. Quote the exact part of the prompt that causes it.
3. Write a 1-sentence fix.

Then rewrite the full prompt with all three fixes applied.

Prompt to review:
"""
[paste the prompt that is giving bad results]
"""

Opens on home with the prompt prefilled.

Open in Promptea

Output comparison: what changed?

Compare these two prompt outputs and explain what instruction change would produce output B instead of output A.

Output A (bad):
"""
[paste the bad output]
"""

Output B (good):
"""
[paste an example of the output you actually want]
"""

Focus on:
- What output format rule was missing in the prompt that generated A?
- What constraint or example would make A impossible and B predictable?
- Write the minimum addition to the original prompt (1–3 lines) that closes the gap.

Opens on home with the prompt prefilled.

Open in Promptea

FAQ

Why does my prompt work sometimes but not others?

Inconsistent outputs usually mean the prompt has ambiguity the model resolves differently each time — no single correct interpretation, so it picks one at random. The fix is to reduce ambiguity: specify the format with an example, constrain the scope with numbers, and remove conflicting instructions. When strict consistency matters, also lower the model's temperature setting if you control it, or lock the output to a JSON schema where one is available.

How many iterations does it usually take to fix a prompt?

Most prompt problems are fixed in 2–3 iterations when you change one thing at a time. Common mistakes that drag it out: changing multiple things at once (so you can't tell what worked), testing only on the original input (missing edge cases), and fixing symptoms instead of root causes. A prompt that handles 5 diverse test inputs reliably is genuinely fixed. One that passes only the original test case will break in production.