Debugging Prompts

Prompts Will Break

In the previous lesson, we explored prompt patterns. Now let’s build on that foundation. Even great prompts fail sometimes. The AI ignores your instructions. The format is wrong. The tone is off. The output is completely beside the point.

Frustrating? Yes. But fixable.

Most people respond to broken prompts by rewriting randomly—changing words, adding context, hoping something works. That’s like debugging code by changing random lines.

This lesson teaches you to debug prompts systematically. Diagnose first, then fix.

The Debugging Process

Step 1: Identify WHAT Is Wrong

Before fixing anything, get specific about the problem. Vague complaints like “it’s not working” aren’t actionable.

Common problem categories:

Name the problem specifically. “The output is in paragraphs but I need a table” is fixable. “It’s bad” is not.

Step 2: Hypothesize the Cause

Once you know what’s wrong, think about why.

Wrong format?

• Did you show an example of the format?
• Is the format instruction clear and specific?
• Did you put the format instruction in a prominent position?

Wrong content?

• Does the AI have enough context to answer correctly?
• Are you asking for knowledge the AI doesn’t have?
• Is the instruction ambiguous?

Ignored instructions?

• Is the instruction buried in the middle?
• Does it contradict another instruction?
• Is it phrased as a suggestion rather than a requirement?

Inconsistent results?

• Is there ambiguity the AI is interpreting differently each time?
• Are you missing examples that would anchor behavior?

Step 3: Test Your Hypothesis

Make ONE change. Run the prompt. Check if the specific problem is fixed.

Don’t change five things at once. You’ll never know what worked.

Step 4: Iterate or Investigate Further

If fixed, done. If not, generate a new hypothesis.

If you’ve tried several obvious fixes without success, use one of the investigation techniques below.

Investigation Techniques

Technique 1: Ask the AI

Seriously. Just ask it.

I gave you this prompt:
[prompt]

You responded with:
[response]

I expected [what you expected] but you [what it did instead].

Why did you interpret my instructions this way? What in my prompt led to this response?

AI is often surprisingly good at diagnosing its own failures. You might discover ambiguity you didn’t see.

Technique 2: Isolation

Remove parts of your prompt until the problem disappears.

1. Start with your full prompt
2. Remove the last section
3. Run it—still broken?
4. Yes → remove more. No → you found the problem section.
5. Now add pieces back to pinpoint exactly what causes it.

This is especially useful for complex prompts where you’re not sure which part is causing issues.

Technique 3: Simplification

Strip the prompt down to basics, then rebuild.

Original (broken):
You are a senior technical writer with 15 years of experience at Fortune 500 tech companies. Your expertise includes API documentation, developer guides, and technical tutorials. You write in a clear, concise style that prioritizes accuracy over marketing language. You always include code examples and follow the Google developer documentation style guide.

Write documentation for this API endpoint: POST /users/create

Simplified test:
Write documentation for this API endpoint: POST /users/create

Quick check: Before moving on, can you recall the key concept we just covered? Try to explain it in your own words before continuing.

If the simplified version works, add pieces back until it breaks. If the simplified version also fails, the problem is more fundamental.

Technique 4: Example Injection

If instructions aren’t working, try showing instead of telling.

Before (instructions only):
Format the output as a markdown table with columns for Feature, Status, and Notes.

After (instruction + example):
Format the output as a markdown table.

Example:
| Feature | Status | Notes |
|---------|--------|-------|
| User login | Complete | Shipped v2.1 |
| Password reset | In Progress | ETA next week |

Examples often succeed where instructions fail.

Common Problems and Fixes

Problem: Wrong Format

Symptoms: Output structure doesn’t match what you asked for.

Fixes:

1. Add an explicit example of the format
2. Move format instructions to the END of the prompt
3. Add “You MUST respond in this exact format:”
4. If asking for JSON, specify: “Respond with valid JSON only. No markdown formatting.”

Problem: Hallucination

Symptoms: AI makes up facts, cites non-existent sources, invents details.

Fixes:

1. Add: “Only use information explicitly provided. Do not make assumptions.”
2. Add: “If you don’t know or aren’t sure, say ‘I don’t have enough information to answer this.’”
3. For factual questions: “Cite specific sources for each claim.”
4. Provide all necessary context—hallucination often fills gaps in provided information.

Problem: Ignoring Instructions

Symptoms: AI does something you explicitly said not to do.

Fixes:

1. Move the instruction to the beginning or end (attention is higher there)
2. Make it stronger: “IMPORTANT:” or “CRITICAL:” prefix
3. Make it a constraint: “You must NOT…” rather than “Please avoid…”
4. Add a negative example showing what NOT to do

Problem: Too Generic

Symptoms: Output is correct but bland, obvious, lacking specificity.

Fixes:

1. Add specific context about your situation
2. Add: “Be specific, not generic. Use concrete examples.”
3. Add constraints that force specificity: “Include at least 3 specific examples from [domain]”
4. Show an example of the specificity level you want

Problem: Inconsistent Results

Symptoms: Same prompt gives different outputs each time.

Fixes:

1. Add few-shot examples to anchor behavior
2. Be more specific about exactly what you want
3. Reduce temperature setting if available
4. Add: “Follow this format exactly every time:”

Problem: Cuts Off Early

Symptoms: Output stops mid-sentence or is incomplete.

Fixes:

1. Ask for output in sections: “First give X, then Y, then Z”
2. If hitting token limits: “Be concise. Maximum 500 words.”
3. Ask for a specific number of items: “List exactly 5 points”

The Debug Log

For complex prompt development, keep a simple log:

Prompt v1: [description]
Problem: [what went wrong]
Hypothesis: [suspected cause]
Change: [what you modified]
Result: [fixed/not fixed/partially fixed]

Prompt v2: [description]
...

This prevents circular debugging—trying the same fixes repeatedly.

When to Give Up

Sometimes a prompt approach just won’t work. Signs to try something different:

• You’ve tried 5+ substantially different approaches
• The task might be beyond current AI capabilities
• Breaking into subtasks might be necessary

Not every task can be solved with one prompt. Sometimes you need to chain multiple prompts, use tools, or approach the problem differently.

Key Takeaways

• Diagnose specifically before fixing—name the exact problem
• Change one thing at a time to know what works
• Ask the AI why it responded that way—it can often explain
• Use isolation and simplification to find problem areas
• Most problems have standard fixes: add examples, reposition instructions, add explicit constraints
• Keep a debug log for complex prompt development

Final lesson: put it all together. You’ll build a production-ready prompt from scratch using everything you’ve learned.

Up next: In the next lesson, we’ll dive into Capstone: Build a Production Prompt.