AI-Assisted Debugging in Cursor

Bug hunting in Cursor runs in three phases with a different mode for each: Ask mode investigates symptoms and ranks hypotheses, Debug mode instruments the code and collects runtime evidence, and Agent mode applies one targeted fix plus a regression test. The sequence exists to prevent the fix-break-fix loop that guessing produces.

Production returns 500s on 15% of checkout requests. It works flawlessly in development. It started after Tuesday’s deployment, but the diff looks harmless — a small refactor of the payment processing logic — and the error message is the supremely unhelpful “Transaction failed.” Your CEO wants an update every thirty minutes.

The tempting move is to paste the error into Agent mode and say “fix this.” It changes three files, your test case passes, and now a different set of users gets a 403. You tell it to fix that too. Two more files. The original 500 is back, and twenty minutes in you are further from a fix than when you started.

The problem is not Cursor. It is treating debugging as “tell the AI to fix it and hope.” Debugging is a search problem, and AI is very good at searching — as long as you make it search before it edits.

What systematic bug hunting gives you

• A three-phase workflow that uses Ask, Debug, and Agent mode for what each is actually good at
• A hypothesis-generation prompt that turns symptoms into ranked, testable theories
• A Debug mode workflow that instruments code, captures runtime data, and finds root causes from evidence
• A load-test prompt for reproducing an intermittent failure locally
• Copy-paste prompts for type errors, race conditions, and a cascade of build errors
• A post-mortem template that documents the bug, the fix, and the prevention

Debugging as a search problem: the three phases

Each phase has a mode, and the mode matters because it constrains what the AI is allowed to do:

1. Investigate in Ask mode. Read-only. You are building a model of the failure, and nothing should change while you do.
2. Gather evidence in Debug mode (or with manual logging). Instrumentation only, no behavior changes.
3. Fix in Agent mode. One targeted change, plus the regression test that proves it.

Skipping straight to phase three is what produces the fix-break-fix loop.

Phase 1: investigate before touching code

Turning symptoms into ranked hypotheses

Collect every observable fact first, then ask for theories you can actually test:

Tip

Copy-paste prompt — symptom analysis:

I have a production bug with these symptoms:

- Error: "Transaction failed" on checkout endpoint (POST /api/checkout)
- Frequency: ~15% of requests, seemingly random
- Environment: production only, cannot reproduce in dev
- Timeline: started after deployment on Tuesday at 14:30 UTC
- Pattern: seems to correlate with traffic spikes but not exclusively
- Error logs show the failure happens in the payment processing step
- No stack trace -- the error is caught and wrapped in a generic message

@src/checkout @src/payment @src/middleware

Based on the code and symptoms, what are the top 5 most likely root causes, ranked by probability? For each hypothesis, tell me:
1. What evidence supports it
2. What evidence would confirm or rule it out
3. What specific log line or metric I should look for

Expect it to name things like connection pool exhaustion, a race condition, a timeout misconfiguration, or a missing error handler on one code path. The ranking matters less than the second and third points: a hypothesis you cannot confirm or rule out is a theory that will waste your afternoon.

Mapping the call chain

When you have a stack trace instead of a symptom list, ask for the path rather than the theory:

Tip

Copy-paste prompt for investigation:

I am seeing this error in production:

[PASTE FULL ERROR MESSAGE AND STACK TRACE]

It affects about 20% of requests to POST /api/orders/create.

Without making any changes, help me understand:
1. What is the call chain from the route to where the error occurs?
2. What are the possible causes based on the stack trace?
3. What data or conditions could make this fail for some users but not others?
4. What additional information would help narrow down the root cause?

Search the codebase for the relevant files.

“Without making any changes” is doing real work in that prompt. It is the difference between a mental model and a surprise diff.

Phase 2: gather runtime evidence

Debug mode

Cursor has a dedicated Debug mode for exactly this. Switch to it with the mode picker, or Cmd+. / Ctrl+. to quick-switch. Unlike Agent mode, it follows a structured investigation:

1. It explores the relevant files and generates hypotheses
2. It adds instrumentation (log statements) that report to a local debug server
3. It asks you to reproduce the bug
4. It analyzes the collected runtime data
5. It proposes a targeted fix based on evidence rather than guesswork

The checkout endpoint at POST /api/checkout is returning "Transaction failed"
for ~15% of requests under load. The error happens in the payment processing
step. I can reproduce it locally using a load testing tool (k6 or similar)
that sends 200 concurrent requests.

Find the root cause using instrumentation.

Debug mode adds logs at the points that matter — database connection acquisition, payment API calls, transaction boundaries — and asks you to trigger the bug. With the runtime data in hand it can usually pinpoint the issue in minutes.

Note

Debug mode works best when you can reproduce the bug locally. If you can only observe the bug in production, provide production logs as context instead and use Ask mode or Agent mode for analysis.

Manual log-and-analyze

When Debug mode is unavailable or you want tighter control, do the same thing by hand. Instrument first:

Tip

Copy-paste prompt for adding diagnostic logs:

Add detailed logging to the order creation flow to help diagnose an intermittent 500 error.

Add logs at these points:
1. Request received (log the full request body and user ID)
2. Before validation (log what the validator receives)
3. After validation (log the validated data)
4. Before database insert (log the query parameters)
5. After database response (log success or error)
6. At the catch block (log the full error with stack trace)

Use our logger from @src/lib/logger.ts with log level 'debug'.
Tag all logs with prefix '[ORDER_DEBUG]' so I can grep for them.

Do NOT change any business logic. Only add logging.

Then reproduce, and bring back two runs rather than one. The comparison is what makes the diagnosis possible:

Tip

Copy-paste prompt for log analysis:

Here are the debug logs from a failed order creation request:

[PASTE LOGS HERE]

And here are logs from a successful request for comparison:

[PASTE LOGS HERE]

Based on the difference between these two executions, what is causing the failure? Be specific about which line of code is responsible and why.

Reproducing an intermittent failure on purpose

If you cannot trigger the bug by hand, have Agent mode build something that can:

Tip

Copy-paste prompt — load test generation:

@src/checkout/route.ts @src/payment/processor.ts

Generate a k6 load test script that:

1. Simulates the exact checkout flow (create cart, add items, initiate checkout, process payment)
2. Ramps from 10 to 200 concurrent users over 60 seconds
3. Uses realistic payment data (varying amounts, different card types)
4. Tracks: response times, error rates by status code, the specific "Transaction failed" error message
5. Reports which requests failed and the exact response body
6. Runs against localhost:3000

The goal is to reproduce the ~15% failure rate we see in production.
Save as tests/load/checkout-stress.js.

A load test that reproduces the failure is worth more than the diagnosis it produces, because it is also how you verify the fix later.

Reading the evidence

@logs/debug-output.log @src/payment/processor.ts

Here are the debug logs from the load test. Analyze them and answer:

1. Which requests failed and what do they have in common?
2. What is the timing pattern? Do failures cluster at specific intervals?
3. Is there a resource that's being exhausted (connections, file handles, memory)?
4. Can you identify the exact line where the failure originates?
5. What is the root cause?

Show me the specific code that needs to change and explain why.

A common finding in this scenario: the payment processor acquires a database connection and fails to release it on certain error paths. Under load the pool exhausts, and the subsequent timeout gets wrapped in the generic “Transaction failed” message — which is why the error text never pointed at the real problem.

Phase 3: the targeted fix

Fix the cause, and only the cause

Switch to Agent mode only now, and constrain it. The template below is the one to keep:

Tip

Copy-paste prompt for targeted fix:

The root cause of the intermittent 500 error in order creation is: [YOUR DIAGNOSIS FROM PHASE 2]

Fix this by:
1. [SPECIFIC CHANGE 1]
2. [SPECIFIC CHANGE 2]

Do NOT refactor other code. Make the minimum change needed to fix this specific issue.

After making the fix:
1. Run the existing tests to make sure nothing else broke
2. Add a test case that reproduces the exact scenario that was failing
3. Remove the debug logging I added earlier (all lines with '[ORDER_DEBUG]')

Filled in for the connection leak above, the same shape becomes concrete — note how much of it is about making the next occurrence diagnosable rather than about the leak itself:

Tip

Copy-paste prompt — fix implementation:

@src/payment/processor.ts

The root cause is a database connection leak: when payment validation fails on line 47, the function returns early without releasing the connection acquired on line 32. Under load, the pool exhausts and subsequent requests timeout.

Fix this by:

1. Moving the validation BEFORE the connection acquisition (no connection needed for input validation)
2. Wrapping the entire connection usage in a try/finally that guarantees release
3. Replacing the generic "Transaction failed" error with specific error types: ValidationError, PaymentGatewayError, ConnectionTimeoutError -- each with a unique error code
4. Adding connection pool metrics logging (pool size, active connections, waiting requests) on every checkout request
5. Creating a regression test in tests/payment/connection-leak.test.ts that verifies the connection is released even when validation fails

Run the load test after the fix to verify the error rate drops to 0%.

The regression test that proves it

Every fix gets a test that would have caught the bug:

Add a regression test for the bug we just fixed.

The test should:
1. Set up the exact conditions that caused the failure (user with [specific condition])
2. Call the endpoint with the same request that was failing
3. Assert that it succeeds with the correct response
4. Also test the edge case where [related condition]

Put the test in @src/routes/__tests__/orders.test.ts following existing patterns.
Run the test to confirm it passes.

If the test fails, the fix was incomplete. If it passes, you have something that stops the bug coming back.

Finding the commit that introduced it

When the bug started after a specific deployment and you have a reliable test, let git do the search:

The checkout load test passes on commit abc123 (Monday) but fails on HEAD (Tuesday).
There are 12 commits between them. Help me set up a git bisect:

1. Create a script that runs the load test and returns exit code 0 if fewer than 1% of
   requests fail, exit code 1 otherwise
2. Show me the git bisect commands to find the exact commit that introduced the regression

Twelve commits narrow to one in about four iterations.

Recurring patterns worth a saved prompt

Type errors that point at the wrong place

TypeScript reports this error at build time:

[PASTE TSC ERROR]

Trace the types involved. Show me:
1. Where the type is defined
2. How it flows through the code to this point
3. Why the types are incompatible
4. The minimal fix that maintains type safety

Do not use `any` or type assertions to fix this. Find the real type issue.

Race conditions

This code has a race condition -- when two requests arrive simultaneously
for the same user, the second request overwrites the first one's data.

Relevant code: @src/services/user-service.ts

Analyze the concurrent execution paths and identify:
1. Which operation is not atomic
2. Where the race window exists
3. The best fix (optimistic locking, database transaction, or mutex)

Show me the fix with before/after code comparison.

A cascade of build errors

With many build errors, fixing them one at a time is the slow path — most of them are downstream of one real problem:

Tip

Copy-paste prompt for build error resolution:

Run `npm run build` (or `tsc --noEmit`) and see the errors.

Fix all build errors. Start with the root causes (often a type change or missing import), not the downstream effects. A single root fix often resolves 5-10 cascading errors.

After fixing, run the build again. Repeat until the build passes.

With auto-run enabled, the agent runs the build, reads the errors, fixes them, and iterates until it passes — the loop Steve Sewell at Builder.io popularized.

Writing the post-mortem

The step most teams skip, and the one with the longest payoff. Draft it in Ask mode while the session is still in context:

Based on this debugging session, write a post-mortem document covering:

1. Summary: what broke, who was affected, how long it lasted
2. Timeline: when it started, when detected, when fixed
3. Root cause: the connection leak in payment processing
4. Fix: what changed and why
5. Detection gap: why our monitoring didn't catch this sooner
6. Prevention: what we will do to prevent similar bugs (connection pool alerting, code review checklist for resource cleanup)
7. Action items with owners and deadlines

Save to docs/postmortems/2026-02-checkout-connection-leak.md

Where AI-assisted debugging goes wrong

You are stuck in the fix-break-fix loop. Phase 1 got skipped. Go back to Ask mode, build the model of the system, then make exactly one targeted change.

Instrumentation changes the bug’s behavior. Log statements alter timing enough that a race condition disappears — the Heisenbug problem. Use lighter instrumentation: increment atomic counters instead of logging strings, or take process.hrtime() timestamps that need no I/O.

The AI produces a plausible but wrong root cause. Models pattern-match well and can be confidently wrong. Verify before implementing: if the diagnosis is right, the fix should drive the load test’s error rate to near zero.

The fix papers over the symptom. The classic bad fix is a retry wrapper around the failing operation instead of plugging the leak. Retries mask pool exhaustion briefly and make it worse under sustained load. Push back and ask for the cause.

The agent “fixes” the test instead of the code. Say it outright: “The test is correct. The implementation is wrong. Fix the implementation to make the test pass.”

The instrumentation does not capture the issue. The bug is somewhere else in the call chain than you assumed. Widen the logging, or reproduce several times — intermittent behavior needs more than one sample.

Nothing reproduces locally. Some bugs need production data volumes, real network latency, or specific hardware. Instrument production with structured logging and analyze it in Ask mode, and have the agent search for known issues in the library or service that is failing.

The trace leads into node_modules. Use @Docs to check the library’s issue tracker and changelog, then ask directly: “Has this library been reported to have connection leaks or timeout issues in recent versions?”

There are too many errors to triage. Fix compile errors first because they block everything else, then runtime errors, then logic errors, using the build-cascade prompt above.

Where to go next after fixing the bug

Testing Patterns Write the tests that stop this class of bug from coming back.

Refactoring Strategies Clean up the structure the bug exposed, once the fix is in.

API Integration Build resilient API integrations with retry logic and circuit breakers that prevent these kinds of failures.

Performance Optimization Proactively find bottlenecks before they become production incidents.