Chapter 05 · Section II · 10 min read
5.2 Iterating: what to change first when it fails
A diagnostic order of operations for improving a prompt that isn't working. Change one thing at a time, in the right order, and know when to stop.
When a prompt fails, the temptation is to rewrite the whole thing. Almost every time this is the wrong move — you end up with a longer, more tangled prompt that fixed nothing and broke two other things. Iterating well means changing one variable at a time, in a specific order, against your eval set.
The one-variable rule
Every change to a prompt is a hypothesis: “if I do X, output will get better.” You can only test that hypothesis if X is the only thing that changed. Rewriting three lines at once and re-running the eval tells you nothing about which line did the work.
Change one thing. Re-run the eval. Record the score. Repeat.
The order of operations
When the eval score is bad, try in this order:
1. Reorder. Move the task to the top and the data to the bottom (Chapter 2.4). Free change, often fixes “the model ignored my instruction” bugs. If the score improves, keep the reorder and stop.
2. Add a format constraint. “Return only the JSON. No preamble.” or “Return exactly three bullets.” Often the output was mostly right but the shape broke your downstream parsing. Fix the shape before fixing the substance.
3. Add one specific negative. From Chapter 3.5 — the exact bad behaviour you saw, forbidden explicitly. “Do not invent statistics.” “Do not translate brand names.”
4. Add one representative example. If zero-shot is close but not there, one worked example (input + expected output) often closes the gap.
5. Add grounding. If the failure is hallucination — the model is inventing facts — provide source material and force it to quote (3.3).
6. Add chain-of-thought. If the failure is reasoning — the model is getting arithmetic or comparisons wrong — add “think step by step” before the answer (3.1).
7. Split into two prompts. If a single prompt is doing extraction and summarisation and translation, split them. One prompt per job.
8. Change the model. Last resort. A stronger model can paper over a weak prompt, but it doesn’t teach you what was wrong.
Stop as soon as you hit an acceptable score. Every additional change is a chance to make things worse.
What to change LAST
- The role. “You are a world-class…” changes are rarely the reason a prompt is failing. Don’t spend iteration budget here.
- The framing. Politeness, tone of the prompt itself. The model doesn’t care.
- Model version. Especially don’t chase a new model release when your prompt hasn’t been tuned. The gains from a strong prompt on the old model usually beat the gains from a weak prompt on the new one.
Reading the eval delta
After each change, look at:
- Overall accuracy. Did the score go up or down?
- Which examples flipped. More useful than the aggregate. Did you fix the intended case but break a different one? That’s a sign the change is fragile.
- Which examples still fail. If the same three examples fail after every change, they may need a different technique (grounding, splitting, or a different model).
Track this in the same spreadsheet you use for the eval set. A column per prompt version, a row per example.
The rollback move
Save prompts as versioned files (prompt-v1.txt, prompt-v2.txt, prompt-v3.txt). When v5 tests worse than v3, roll back to v3 and try a different branch. Without versioning, you lose track of “the prompt from last Tuesday that worked well” and can’t recover it.
When to stop iterating
Stop when one of three things is true:
- You’ve hit an acceptable score on the eval set. Ship.
- You’ve plateaued. Three or four consecutive changes have moved the score by less than a percentage point in either direction. Time to consider grounding, splitting, or a different model.
- The prompt has grown into something you don’t understand any more. Delete it, keep the eval set, and rewrite from scratch. Sometimes cleaner is faster than clever.
Check your understanding
Quick check
—