AI-Assisted Debugging: From Bug Report to Tested Fix

Start with a reproducible failure, ask the agent to explain its cause, and keep the patch narrow. A regression test should fail before the change and pass after it. That is stronger evidence than an explanation that merely sounds plausible.

This guide uses a deliberately small pagination defect. It is a teaching example, not a production incident or a model benchmark. You can reproduce it with Node.js and its built-in test runner; no API key or package install is needed.

Reproduce the bug

Bug report: a list has 21 items and displays 10 per page. The navigation shows two pages, so the final item is unreachable. Expected: three pages.

The faulty calculation rounds down:

return Math.floor(total / pageSize);

Download the broken implementation and regression tests into an empty directory. Save the broken implementation as pagination.mjs, keeping the tests named pagination.test.mjs.

node --test pagination.test.mjs

The partial-page test should fail with actual 2, expected 3. The other tests cover exact multiples, empty lists, and invalid inputs. Confirm the failure is the assertion you expected, not an import error.

Give the agent evidence

Bug: 21 items at 10 items per page shows 2 pages; expected 3.
Read pagination.mjs and pagination.test.mjs.
Run the tests and explain the failing calculation before editing.
Make the smallest fix. Preserve the input validation and empty-list behaviour.
Do not modify the tests to accept the current result.
Run the tests again and report both outcomes.

The useful context is the expected result, actual result, relevant code, and a test the agent can run. A whole application's logs would add noise to this particular problem.

Apply the minimal patch

- return Math.floor(total / pageSize);
+ return Math.ceil(total / pageSize);

Rounding up counts a final partial page. Exact multiples remain unchanged, and zero items still yields zero pages. Keep the existing validation for non-negative integer totals and positive integer page sizes.

The complete fixed implementation is available for comparison. Run the same command again: all four tests should pass. Review the diff to confirm only the calculation changed.

Verify the real application too

A passing utility test establishes the calculation, not the entire UI. In a real app, reproduce the original report in the browser, navigate to the third page, and confirm it displays the final item. Check the empty-list state and an exact multiple too. Ensure the UI and API use the same page-size and page-number conventions.

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.

With Cursor's built-in Agent browser available, 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.

Keep the debugging loop small

1. Record expected and actual behaviour and reliable reproduction steps.
2. Inspect relevant runtime evidence before making changes.
3. Isolate the smallest failing example and add a regression test.
4. Ask the agent to diagnose the cause and propose a narrow patch.
5. Run the unchanged regression test and relevant neighbouring tests.
6. Recheck the original user flow and inspect the final diff.

If a fix changes unrelated files or the agent cannot explain why it works, stop expanding the patch and return to the evidence. See Diff Review Loops for the final review, or copy a debugging workflow.