Debugging Prompts

A prompt has worked for weeks. Then someone forwards a bad reply. You add a line, "Be careful with this kind of request", try the bad case again, and it looks fine. A week later, three different cases that used to work are broken, and nobody knows which edit did it.

That is debugging by feel. Prompts deserve the same habits as code: reproduce the problem, test against a fixed set of cases, change one thing at a time, and check you did not break anything else.

#The loop

1. Collect cases. Gather 5 to 20 real inputs: the ones that failed, plus a spread of ones that already work. Write down the right answer for each.
2. Run them all and record which pass.
3. Read the failures next to the prompt, and guess why. Name one cause.
4. Change one thing that targets that cause.
5. Rerun every case, not just the one you were fixing. Keep the change only if the total got better and no important case broke.

Step 5 is the one people skip. A prompt is a single piece of text that affects every input, so a fix for one case can quietly change many others.

#A debugging session

A support team uses a prompt to label incoming tickets as urgent, normal or low. They collected six tickets and the label each should get. The tracer follows an illustrative session through three versions of the prompt.

Notice what the fix was not: "If the ticket mentions payroll, label it urgent." That passes the test and teaches the model nothing about the next ticket, which will mention invoices. Fix the cause, not the case.

#Finding the cause

Most prompt bugs come from a short list of causes. Match the symptom first.

A useful trick when you cannot see the cause: ask the model. Add "Before the label, explain in one sentence which words in the ticket decided it." The explanation is not a reliable account of how the model really reached its label, but it often shows which part of your prompt or input it latched onto.

#A tiny test runner

Once you have more than a few cases, run them with code. The runner below takes your cases and any function that returns a label. In real use that function sends the prompt and the ticket to a model; here a stand-in returns fixed answers so you can run it as is.

function runTests(cases, getLabel) {
  const failures = [];
  for (const c of cases) {
    const got = getLabel(c.ticket);
    if (got !== c.expected) failures.push(`${c.ticket}: expected ${c.expected}, got ${got}`);
  }
  console.log(`passed ${cases.length - failures.length} / ${cases.length}`);
  for (const f of failures) console.log("  " + f);
}
 
const cases = [
  { ticket: "Calm: no one can pay", expected: "urgent" },
  { ticket: "FURIOUS about typo", expected: "low" },
  { ticket: "Reports page slow", expected: "normal" },
];
// Stand-in for a real model call, behaving like prompt v1:
const v1 = { "Calm: no one can pay": "normal", "FURIOUS about typo": "urgent", "Reports page slow": "normal" };
runTests(cases, (ticket) => v1[ticket]); // passed 1 / 3

def run_tests(cases, get_label):
    failures = []
    for c in cases:
        got = get_label(c["ticket"])
        if got != c["expected"]:
            failures.append(f'{c["ticket"]}: expected {c["expected"]}, got {got}')
    print(f"passed {len(cases) - len(failures)} / {len(cases)}")
    for f in failures:
        print("  " + f)
 
cases = [
    {"ticket": "Calm: no one can pay", "expected": "urgent"},
    {"ticket": "FURIOUS about typo", "expected": "low"},
    {"ticket": "Reports page slow", "expected": "normal"},
]
# Stand-in for a real model call, behaving like prompt v1:
v1 = {"Calm: no one can pay": "normal", "FURIOUS about typo": "urgent", "Reports page slow": "normal"}
run_tests(cases, lambda ticket: v1[ticket])  # passed 1 / 3

Model replies vary from run to run, as Sampling and Temperature explains. So run each case a few times. A case that passes 2 times out of 3 is a real problem, even though a single run might have hidden it. Growing this runner into a proper test suite is the subject of Evals.

#Try it yourself

#Common mistakes

#Check yourself

#What to practise next

Some bad replies are not your prompt's fault at all: they come from text that someone else slipped into the input. That is Prompt Injection, the last lesson in this module.