Prompt Debugging Checklist

Why you need this

You know what you want from AI, but the results keep missing the mark. The response is too generic, too verbose, factually wrong, or just misses the point entirely. You try rewording your prompt five different ways with minimal improvement, growing more frustrated with each attempt.

The problem: When prompts fail, most people guess randomly at fixes—making prompts longer, adding more detail, trying completely different approaches. Without a systematic debugging process, you waste time on trial-and-error instead of quickly identifying and fixing the actual issue.

This checklist solves that. It provides a structured diagnostic framework that helps you identify exactly why a prompt isn't working and what to change to fix it, dramatically reducing the time from problem to solution.

Perfect for:

• Professionals relying on AI for work deliverables who need consistent results
• Prompt engineers optimizing prompts for production systems
• Content creators frustrated by inconsistent AI output quality
• Anyone who's tried a prompt multiple times without getting what they need

What's inside

Diagnostic Framework

The 5 Categories of Prompt Failure:

1. Clarity issues: AI doesn't understand what you're asking
2. Context gaps: Missing information needed to answer properly
3. Constraint problems: Instructions conflict or aren't specific enough
4. Capability mismatches: You're asking for something beyond the AI's abilities
5. Output format errors: Response structure doesn't match your needs

Quick Diagnostic Questions:

• Is the AI confused about what I want, or does it understand but produce the wrong thing?
• Did I provide enough context and examples?
• Are my instructions specific and unambiguous?
• Am I asking the AI to do something it fundamentally can't do?
• Is the response good but formatted wrong?

Category 1: Clarity Issues

Symptoms:

• AI asks clarifying questions
• Response addresses the wrong topic
• Output is too general or vague
• AI makes incorrect assumptions

Debugging checklist:

• ❏ Is my core request clearly stated in one sentence?
• ❏ Did I use jargon or ambiguous terms the AI might misinterpret?
• ❏ Are there multiple possible interpretations of my prompt?
• ❏ Did I bury the main request in surrounding text?

Fixes:

• Start with explicit instructions: "Write a...", "Analyze...", "Create..."
• Define ambiguous terms: "By 'aggressive', I mean..."
• Separate background context from the actual request
• Front-load the most important instruction

Example:

• ❌ Unclear: "Something about marketing trends"
• ✅ Clear: "List the top 5 digital marketing trends in 2025, with a brief explanation of each"

Category 2: Context Gaps

Symptoms:

• Response is generic and could apply to anyone
• AI gives textbook answers instead of tailored advice
• Missing key nuances you expected
• Response assumes things not specified

Debugging checklist:

• ❏ Did I specify my audience, industry, or use case?
• ❏ Have I provided relevant background information?
• ❏ Did I share examples of what success looks like?
• ❏ Are there constraints or requirements I forgot to mention?

Fixes:

• Add role/persona: "I'm a [role] at a [company type]..."
• Provide situational context: "The goal is...", "My audience is..."
• Share examples: "Similar to [example], but..."
• Specify constraints: "Must be under 200 words", "Avoid technical jargon"

Example:

• ❌ Missing context: "Write an email about the meeting"
• ✅ Rich context: "Write a professional email to my team summarizing yesterday's Q3 planning meeting. Key decisions: approved budget increase, delayed launch to October, hired 2 new engineers. Tone: informative but optimistic. Length: 3 short paragraphs"

Category 3: Constraint Problems

Symptoms:

• Output is way too long or too short
• Tone is wrong (too formal, too casual, too robotic)
• Format doesn't match what you asked for
• Response includes things you explicitly said to exclude

Debugging checklist:

• ❏ Did I specify desired length or level of detail?
• ❏ Have I described the tone and style I want?
• ❏ Did I request a specific format or structure?
• ❏ Are any of my instructions contradictory?
• ❏ Did I list what NOT to include?

Fixes:

• Set explicit constraints: "Exactly 5 bullet points", "Under 100 words", "Use casual language"
• Provide formatting instructions: "Format as a table with columns for...", "Use H2 headers for sections"
• Add negative constraints: "Do not include...", "Avoid..."
• Check for conflicting instructions and resolve them

Example:

• ❌ Vague constraints: "Make it professional but not boring"
• ✅ Clear constraints: "Write in a conversational but professional tone—like a knowledgeable colleague, not a corporate press release. Use short paragraphs (3-4 sentences max). Include 1-2 light examples to illustrate points. 300-400 words total."

Category 4: Capability Mismatches

Symptoms:

• AI says it can't do what you're asking
• Responses contain factual errors or hallucinations
• Output quality is consistently poor despite prompt tweaks
• AI provides outdated information (knowledge cutoff issues)

Debugging checklist:

• ❏ Am I asking for real-time or post-cutoff information?
• ❏ Am I requesting subjective judgments the AI can't make?
• ❏ Does this task require capabilities the AI doesn't have (accessing websites, executing code, personal opinions)?
• ❏ Am I asking for proprietary or specialized knowledge?

Fixes:

• Use web search mode for current information
• Provide source material: "Based on this document...", "Using this data..."
• Break complex tasks into simpler steps
• Accept limitations: some tasks genuinely need human judgment
• Verify facts independently (especially dates, statistics, citations)

Example:

• ❌ Beyond capabilities: "What are today's stock prices for Apple?"
• ✅ Within capabilities: "Based on historical trends, what factors typically influence Apple's stock price?"

Category 5: Output Format Errors

Symptoms:

• Content is good but structure is wrong
• Response is one long paragraph instead of organized sections
• Lists aren't bulleted/numbered as requested
• Code blocks, tables, or formatting missing

Debugging checklist:

• ❏ Did I specify the exact format I want?
• ❏ Have I provided a structural template to follow?
• ❏ Did I use clear formatting keywords (bullet, table, code block)?
• ❏ Should I have provided an example of desired output?

Fixes:

• Use explicit formatting language: "Format as a numbered list", "Create a markdown table", "Use bullet points"
• Provide templates: "Structure the response like this: [template]"
• Show examples: "Like this example: [paste example]"
• Request specific elements: "Include H2 headers", "Separate with line breaks"

Example:

• ❌ Unclear format: "Compare these products"
• ✅ Clear format: "Create a comparison table with columns for Product Name, Price, Key Features, and Pros/Cons. Include 3 products."

Advanced Debugging Techniques

Iterative Refinement:

1. Start with basic prompt
2. Identify which category of failure occurred
3. Apply targeted fix from that category
4. Test and iterate only on what's still broken

Prompt Versioning:

• Keep track of what you tried and what happened
• Document what worked and what didn't
• Build a library of successful prompts for similar tasks

Testing Variations:

• Change one thing at a time (don't redesign the entire prompt)
• Test with simpler examples first
• Use the same prompt across different AI tools to identify tool-specific issues

How to use it

• When stuck — Work through the diagnostic questions to identify the problem category, then apply targeted fixes
• Quality control — Use as a pre-flight checklist before sending important prompts
• Team training — Share with colleagues to establish consistent prompt debugging practices
• Optimization — Refine production prompts systematically instead of randomly

Example: Before & after debugging

Original prompt (failing):
"Write about AI safety"

Problem diagnosis:

• Category 1 (Clarity): Too vague—"write about" could mean many things
• Category 2 (Context): No audience, purpose, or depth specified
• Category 3 (Constraints): No length, tone, or format guidance

Debugged prompt:
"Write a 400-word blog post introduction explaining AI safety for non-technical business leaders. Focus on why it matters for companies deploying AI, not technical implementation details. Tone: informative but accessible, not alarmist. Structure: hook (surprising stat or scenario), why it matters now, 3 key risk categories in brief, transition to full article."

Result: Focused, appropriately scoped content that matches exact needs instead of generic overview.

Want to go deeper?

This checklist covers prompt troubleshooting. For comprehensive prompting guidance:

• Guide: Prompting 101 — Master prompt engineering fundamentals
• Guide: AI at Work Basics — Best practices for professional AI use
• Glossary: Prompt — Understanding how prompts work
• Glossary: AI — AI capabilities and limitations

License & Attribution

This resource is licensed under Creative Commons Attribution 4.0 (CC-BY). You're free to:

• Share with your team or community
• Customize for your specific AI tools and use cases
• Integrate into training and documentation

Just include this attribution:

"Prompt Debugging Checklist" by Field Guide to AI (fieldguidetoai.com) is licensed under CC BY 4.0

Access now

Ready to explore? View the complete resource online—no signup or email required.