Bug Report to Fix

Debugging with AI has a clear failure mode: paste a stack trace, ask "what's wrong?", get a plausible-sounding but wrong answer. The model doesn't have enough context to diagnose the real issue, so it pattern-matches to the most common cause of that error.

The fix is the same as good debugging in general: minimal reproduction first. Once you have that, the model has enough context to actually help.

The minimal repro step

Most people skip this. It's the most important step. A minimal repro is the smallest amount of code that demonstrates the bug — and creating it forces you to understand the bug well enough to isolate it. Often you find the bug yourself in the process.

When you do need model help, "here's a 10-line example that reproduces the bug" is dramatically more useful than "here's my 500-line component that has a bug somewhere."

When the bug lives in the browser

For frontend bugs, don't debug from a pasted error string alone. Open the app in Cursor's browser, reproduce the bug there, and look at actual runtime signals: console logs, failed network requests, warnings, visible DOM state, whether the UI breaks before or after an interaction.

A lot of bugs are only obvious in the browser — hydration mismatches, broken form submissions, race conditions after navigation, event handlers that never fire, client-side state that diverges from what the server rendered. A terminal stack trace often misses the part you actually need.

If you have Browser MCP connected, the debugging loop gets tighter. Instead of saying "the page looks broken," you can ask the model to open the page, reproduce the issue, inspect the browser state, and use that evidence as part of the diagnosis. That's much better context than screenshots or vague descriptions.

Cursor's Debug Mode

When standard Agent interactions struggle with a bug — especially ones you can reproduce but can't explain, race conditions, timing issues, or regressions — Debug Mode takes a different approach. Instead of guessing at fixes, the agent generates hypotheses, adds log instrumentation, and uses runtime evidence to pinpoint the root cause before making a targeted fix. The loop is: explore and hypothesize → add instrumentation → reproduce the bug → analyze logs → fix → verify and remove instrumentation. Switch to it via the mode picker dropdown in Agent or press Shift+Tab.

The debugging flow

Step 1: Reproduce. Can you reliably reproduce the bug? If not, start there. A bug you can't reproduce is much harder to fix. For UI bugs, reproduce it in Cursor's browser instead of describing it from memory.

Step 2: Inspect runtime evidence. Before changing code, check what the browser is telling you: console output, failed requests, warnings, broken DOM state, and whether the bug appears on load or only after interaction.

Step 3: Isolate. Strip away everything that isn't necessary to reproduce the bug. Remove dependencies, simplify data, reduce to the smallest case.

Step 4: Diagnose. With the minimal repro in hand, ask the model to explain what's happening and why. "Here's a minimal example that demonstrates the bug. What's causing it?" If Browser MCP is available, include what it saw in the browser as part of the prompt.

Step 5: Fix. Implement the fix. Keep it narrow — fix the specific bug, don't refactor adjacent code.

Step 6: Regression test. Write a test that would have caught this bug. "Write a test that verifies this specific behavior." This is the most valuable step — it prevents the bug from coming back.

What I've learned about AI-assisted debugging

Models are good at pattern recognition — they've seen most common bugs before. Less good at reasoning about your specific system's behavior. More context (the minimal repro, expected vs actual behavior, the relevant code) = better results.

Browser context helps too. A model that can see the runtime evidence is less likely to invent a plausible-sounding cause that doesn't match what's actually happening.

The failure mode to watch for: a fix that addresses the symptom but not the cause. Always ask "why does this fix work?" If the explanation doesn't hold up, the fix might be wrong.