Prompt Like a Pro
Chapter 6 of 10

The Debug Playbook

When Things Break

Chapter 6: When Things Break - The Debug Playbook

The Reality Check

Here’s what nobody tells you about building with AI: things will break. Not because you did something wrong, but because building websites is complicated and AI agents sometimes hallucinate solutions that sound great but don’t actually work.

I’ve been there. I once spent three hours trying to figure out why my cleaning business site’s contact form wasn’t sending emails. The AI had confidently written code that looked perfect but was missing one tiny configuration detail. The difference between frustration and solution was knowing what questions to ask.

This chapter is your debug playbook - the specific prompts and strategies that turn “this is completely broken” into “oh, that’s what was wrong.”

The Three Types of Breaking

When something goes wrong, it usually falls into one of these categories:

Visual Breaking: It looks wrong but technically works. Your header is enormous, text is invisible on the background, buttons are in weird places. The functionality is there, but the appearance is broken.

Functional Breaking: It looks fine but doesn’t do what it’s supposed to. Forms that don’t submit, links that go nowhere, search bars that don’t search.

Complete Breaking: The whole thing is just… error messages. Usually means something in the code is fundamentally wrong.

Identifying which type you’re dealing with saves time because each has different solutions.

The Debug Framework That Actually Works

Step 1: The Screenshot Method

Before you type anything to your AI agent, take screenshots. Seriously. Here’s why this matters:

When I was fixing the Pomodoro timer, I kept describing what was broken: “the timer doesn’t stop when I click pause.” The AI kept giving me solutions that didn’t work because I wasn’t being specific enough about what was happening.

Then I took screenshots showing:

  • What the pause button looked like when clicked
  • What the console errors said
  • What the timer display was doing

Suddenly the AI understood: the button wasn’t connected to the timer logic properly.

Prompt Formula:

I'm attaching three screenshots showing the issue:
1. [Screenshot of how it currently looks]
2. [Screenshot of what it should look like OR description]
3. [Screenshot of any error messages]

The specific problem: [describe in one sentence what's not working]

Walk me through what's likely causing this and how to fix it.

Step 2: The Error Message Translator

Error messages look scary but they’re incredibly helpful - if you know how to read them. You don’t need to understand every word. You just need to give your AI agent the right information.

From my directory project, here’s an actual error I encountered:

TypeError: Cannot read property 'map' of undefined

Terrifying, right? But here’s what I learned: error messages tell you two critical things:

  1. What TYPE of error (TypeError, ReferenceError, SyntaxError)
  2. WHERE it happened (usually a line number or file name)

The Translation Prompt:

I'm getting this error message:
[paste the ENTIRE error message, even the scary parts]

What I was trying to do when this happened:
[e.g., "click the search button" or "load the page"]

In non-technical terms, what does this error mean and how do I fix it?

The AI doesn’t need you to understand the error. It just needs the full context you can see.

Step 3: The “It Was Working” Prompt

This is the most important question in debugging: when did it break?

For my cleaning business site, the mobile menu was working perfectly. Then I asked the AI to add a new section, and suddenly the menu stopped opening on phones. The AI’s first solution didn’t work. Neither did the second.

The breakthrough came when I used this prompt:

Here's what was working: [describe the working state]

Here's what I asked you to add/change: [describe what you modified]

Here's what broke: [describe current broken state]

The changes we made likely affected each other. Can you:
1. Explain how these features might be conflicting
2. Provide a solution that keeps both working
3. Show me which specific code changes to make

This gives the AI the timeline it needs to understand cause and effect.

Common Bugs and Their Instant Fixes

The Invisible Text Bug

Symptom: Text disappears on certain backgrounds Quick Fix Prompt:

My text is invisible/hard to read on [background color/image].
Ensure readable contrast by:
1. Setting text color to [preferred color]
2. Adding a subtle shadow or background overlay if needed
3. Checking that all text in this section has proper contrast

Show me the CSS changes to make.

The Mobile Menu Won’t Open

Symptom: Hamburger icon appears but clicking does nothing Quick Fix Prompt:

The mobile menu icon appears but clicking it doesn't open the menu.
Debug the hamburger menu by:
1. Checking if the click event is properly attached
2. Verifying the menu toggle function works
3. Ensuring no z-index issues are blocking clicks

Provide the corrected JavaScript and any CSS changes needed.

The Form That Goes Nowhere

Symptom: Submit button does nothing or page refreshes without sending Quick Fix Prompt:

My form's submit button [describe what happens - nothing/page refreshes/error].
Check and fix:
1. Form action and method settings
2. Submit button type and event handling
3. Any JavaScript preventing default behavior

Show me exactly what to fix and where.

The Layout That Breaks on Mobile

Symptom: Everything is squished, overlapping, or broken on phones Quick Fix Prompt:

My layout looks perfect on desktop but breaks on mobile:
[describe specific issues - text overlapping, images too big, etc.]

Make this mobile-responsive by:
1. Adding proper viewport settings
2. Creating mobile-specific breakpoints at [your preferred widths]
3. Adjusting [specific elements] for smaller screens

Provide the responsive CSS needed.

The Nuclear Option: Starting Fresh (Without Losing Everything)

Sometimes you’ve gone down such a rabbit hole that the easiest path is starting over. But you don’t have to lose your work.

The Smart Reset Prompt:

I want to rebuild [specific component] from scratch, but keep these working parts:
- [list features that DO work]
- [list styling you want to preserve]

Start fresh on [broken component] while preserving everything I listed.
Show me the new code for just the component we're rebuilding.

I used this on my Pomodoro timer when the settings panel became a tangled mess. Instead of debugging 200 lines of confused code, I had the AI rebuild just the settings panel while keeping the working timer display and controls.

Prevention Strategies

The One Change Rule

After my directory site debugging nightmare, I learned this lesson the hard way: make ONE change at a time.

When you ask your AI to:

  • Add a new feature
  • Change colors
  • Update the layout
  • Fix a bug

…all in one prompt, you’re setting yourself up for detective work when something breaks. You won’t know which change caused the problem.

Better approach:

Make only this change: [single specific change]

Before you show me the code, confirm:
1. What files will be modified
2. What could potentially break from this change
3. How to revert if needed

The Version Marker System

This is stupid simple but incredibly effective. When something works, tell your AI:

Mark this as Version [X] - working state before we [describe next change].
Save this code state so we can return to it if needed.

Most AI agents can remember this context. When things break, you can say: “Go back to Version 3 and let’s try a different approach.”

Real World Debug Session

Let me show you how this actually works in practice. This is from my cleaning business site:

The Problem: Contact form wasn’t sending emails (even though AI said it worked)

Debug Session:

Me:

The contact form appears to submit (button shows "sending..." then "sent!") 
but no email arrives. I've checked spam folders.

Error in browser console: [screenshot of console showing 403 error]

Walk me through what's likely wrong and how to diagnose it.

AI Response identified the issue: the email API needed authentication configuration. But I didn’t know how to add that.

Me:

You mentioned I need to configure email API authentication.
I don't know what that means. Show me:
1. Where exactly this configuration goes
2. What specific information I need to provide
3. Step-by-step instructions in plain language

AI then provided the exact steps, and it worked. The key was admitting I didn’t understand and asking for simpler instructions.

The Emergency Checklist

When everything feels broken and you’re stuck:

□ Did I take screenshots of the error/issue? □ Did I copy the complete error message? □ Can I describe when it last worked? □ Am I trying to fix multiple things at once? □ Have I asked the AI to explain in simpler terms?

Usually, running through this checklist reveals what information I was missing from my debug prompt.

What This Chapter Gives You

You now have:

  • A framework for translating “broken” into fixable problems
  • Specific prompts for the most common bugs
  • A strategy for debugging without getting lost
  • Real examples from actual projects
  • The confidence to say “I don’t understand, explain simpler”

Debugging isn’t about being technical. It’s about being systematic, specific with your prompts, and knowing that “start over” is sometimes the smartest move.

Next up: Chapter 7 tackles the scary part - making your creation actually live on the internet where people can see it.