Lesson 5: Debugging and Improving Prompts

Learning goals:

• Learn to spot prompt problems systematically
• Build a method for diagnosing why a prompt fails
• Set up a repeatable loop for improving prompts

Prerequisites: << Lesson 4: Chain-of-Thought: Making AI Show Its Reasoning | Next: Lesson 6 >>

What to do when a prompt doesn't work

You wrote a careful prompt with a role, a task, a format, and examples, and the AI still gets it wrong. Maybe the format is off, the content drifted, or a key piece of information is missing. Now what?

Change a few words at random and hope the next run is luckier? Or track down the problem and fix it on purpose? This lesson teaches the second approach: debug a prompt the way you debug code. Spot the symptom, diagnose the cause, make a small change, and check the result.¹

The three-step debugging loop

Debugging a prompt works a lot like debugging code.¹

1. Identify the problem: what exactly is wrong with the output?
2. Diagnose the cause: which part of the prompt produced that problem?
3. Change and verify: change one thing, then test whether it improved.

The rule that matters most: change one variable at a time. If you change three things at once, you won't know which change did the work.

Step 1: Identify the specific problem

"The output is wrong" is too vague. Pin down what's actually wrong.¹

Common problem types:

Example: identifying the problem

Your prompt:

Summarize the key points of this article.

The AI's output:

This article covers three key points. First... Second... Finally...

Problem identified: it isn't the list format you wanted, and you never said how many points.

Step 2: Diagnose the cause

Find which part of the prompt (or which missing part) caused the problem.

A diagnosis checklist:

• Is the task clear? "Summarize the key points" is fuzzy. It never says how many points or how long each one should be.
• Is there a format example? No. The AI can only guess what shape you want.
• Are the constraints enough? Nothing says "output only the points, no lead-in."
• Is anything ambiguous? "Key points" could mean "core arguments" or "every claim."

Diagnosis: the format spec and a count constraint are missing.

Step 3: Make a small change, then verify

Fix one problem at a time and test whether it improved.

Change 1: state the count and format

Summarize this article in three bullet points, one sentence each.

Test result: the format is right, but each point runs longer than a sentence.

Change 2: add a length constraint

Summarize this article in three bullet points.
Requirements:- Each point is 15 words or fewer- Use a bulleted (- ) list- Output only the points, no lead-in like "Here are the key points"

Test result: matches what you wanted.

Write down the change that worked so you can reuse it next time you hit the same problem.

Diagnosing and fixing common problems

Problem 1: unstable format

Symptom: sometimes JSON, sometimes plain text; sometimes a colon, sometimes an equals sign.

Diagnosis: no format example, or examples that don't match each other.

Fix:

• Give 2-3 examples that all use exactly the same format
• Or state it in the constraints: "Follow this JSON format exactly and output nothing else."

Problem 2: missing information

Symptom: the output has only part of the data and always drops certain fields.

Diagnosis: you never listed the information you need.

Fix:

Extract all of the following fields (all required):1. Title2. Author3. Publication date4. Summary
If a field isn't in the source, output "not provided" rather than omitting the field.

The key is to list every required field and say what to do when one is missing.

Problem 3: over-explaining

Symptom: you asked for code and got code plus a wall of explanation; you asked for a list and got an intro and a summary wrapped around it.

Diagnosis: no "output only X" constraint.

Fix:

Output runnable code only. No explanation, comments, or notes.

Or:

Output the list only. No lead-in like "Here is the list" and no summary.

Problem 4: misread intent

Symptom: the AI misread what you meant and answered a related but wrong question.

Diagnosis: ambiguous wording, or missing context.

Example:

Analyze the problems in this code.

The AI might analyze:

• Style problems
• Performance problems
• Security problems
• Logic errors

You wanted logic errors, but the prompt never said so.

Fix:

Analyze the logic errors in this code. Ignore style and performance; focus only on logic bugs that would produce wrong output.

Name the dimension you want and rule out the rest.

Best practices for iterating

Practice 1: build a set of test cases

Prepare 3-5 representative inputs and run every change against all of them.¹

Example: you're tuning a prompt that extracts sentiment from product reviews.

Test cases:

1. Clearly positive: "Very happy with it, highly recommend."
2. Clearly negative: "Completely unusable, waste of money."
3. Neutral / mixed: "Works fine, but a bit pricey."
4. Edge case: "It's okay I guess."
5. Complex: "Support was great, but the product quality is mediocre."

After each change to the prompt, run all five and check whether they all classify correctly.

Practice 2: track versions and results

Manage prompt versions the way you manage code versions.¹

A simple log:

v1 (2024-01-15):Extract the sentiment of the review.
Result:- Clear cases OK- Edge cases unstable
---
v2 (2024-01-15):Classify the review as "positive", "negative", or "neutral".Examples: [3 examples]
Result:- Edge cases improved- But output format isn't consistent (sometimes "positive", sometimes "Positive")
---
v3 (2024-01-15):[v2 content] + constraint: output exactly one of the lowercase words positive, negative, or neutral.
Result: passes all test cases

Now you know what each change bought you, and if a new version turns out worse you can roll back to the last good one.

Practice 3: A/B test the changes you're unsure about

Not sure a change actually helps? Keep both versions, run each one 10 times, and compare the success rate. That's an A/B test: change one factor at a time and let the data decide.

Example: you're not sure whether adding "let's think step by step" really helps.

• Version A (without): 10 runs, 7 correct
• Version B (with CoT): 10 runs, 9 correct

The data speaks. B is better.

Practice 4: start from a simple version

Don't open with a 500-word monster prompt. Start with the simplest version and add constraints as you go.¹

An iteration path:

v1: Summarize this article.   -> too vague
v2: Summarize the core points of this article in three bullets.   -> bullets run too long
v3: Summarize the core points in three bullets, each 15 words or fewer.   -> format still inconsistent
v4: [v3] + use a bulleted list, output only the points with no lead-in.   -> works well

Each step fixes exactly one problem, and you end up with a prompt that's just enough, with no filler.

The debugging loop, end to end

The full loop is a cycle: run the prompt, check the output, and if it doesn't match, identify the problem, diagnose the cause, change one thing, verify with your test cases, repeat until it matches, then record the working version.

The diagram below shows each step of that loop:

graph TD    A[Run the prompt] --> B{Output as expected?}    B -->|Yes| C[Record the working version]    B -->|No| D[Identify the specific problem]    D --> E[Diagnose the cause]    E --> F[Change one thing]    F --> G[Verify with test cases]    G --> B    C --> H[Archive to your prompt library]

Core principles:

• Change one thing at a time
• Verify every change with test cases
• Track versions and their results
• Start simple and add constraints as needed

When to stop tuning

Prompt tuning has no natural end, but it has a good-enough bar:

Signs you can stop:

• Success rate on your test cases is 90% or higher
• Output format is stable
• You can explain what every part of the prompt does
• The next improvement would cost more time than it's worth

Signs you should keep going:

• Success rate below 70%
• The same input gives wildly different output each run
• You're not sure some parts of the prompt do anything
• It keeps failing on edge cases

A pragmatic rule: good enough is good enough, don't chase perfect. If it works well 90% of the time, a human can step in for the remaining 10% of edge cases.

Recap

The prompt debugging loop is: identify the specific problem, diagnose the cause, make a small change, verify. The key is to change one variable at a time, verify every change with test cases, and track versions and results.

Common problems include unstable format, missing information, over-explaining, and misread intent. Each has a matching fix: add examples, list the fields, add an "output only" constraint, and rule out ambiguity.

Start from a simple version and add constraints until your success rate on the test cases clears 90%. Record the prompt versions that work so you can reuse them next time.

The next lesson covers prompt strategies for different task types: what's specific to code generation, document writing, and data analysis.

Next lesson Prompt Strategies for Different Tasks >>