Debugging Workflows

Your API endpoint returns a 500 error, but only for certain users. You paste the error into Cursor Agent mode and say “fix this.” It changes three files, the error goes away for your test case, but now a different set of users gets a 403 error. You tell Agent to fix that too. Two more file changes. Now the original 500 is back. You have been going back and forth for 20 minutes and you are further from a fix than when you started.

The problem is not Cursor. The problem is treating debugging as “tell the AI to fix it and hope.” Effective AI-assisted debugging is a structured process: investigate first, understand the root cause, then apply a targeted fix.

What You’ll Walk Away With

• A systematic debugging workflow using Ask, Debug, and Agent modes in sequence
• Copy-paste prompts for each stage of the debugging process
• Techniques for using logs, error traces, and runtime data with AI
• Patterns for preventing the “fix-break-fix” loop

The Three-Phase Debugging Workflow

Phase 1: Investigate (Ask Mode)

Before touching any code, understand what is happening:

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.

This gives you a mental model of the problem before you start changing things.

Phase 2: Gather Evidence (Debug Mode or Manual Logging)

Once you have hypotheses, gather runtime evidence to confirm or rule them out.

Option A: Use Debug Mode

Switch to Debug mode and describe the bug. The agent will:

1. Generate hypotheses about root causes
2. Add strategic log statements to the code
3. Ask you to reproduce the bug
4. Analyze the captured logs
5. Identify the root cause based on evidence

Option B: Manual Log-and-Analyze

If Debug mode is not available or you prefer manual control:

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.

After reproducing the bug, paste the logs back into Cursor:

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.

Phase 3: Targeted Fix (Agent Mode)

Only after you understand the root cause, switch to Agent mode for the fix:

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]')

The Fix-Then-Verify Pattern

After every fix, verify it actually works by adding 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, you know the fix was incomplete. If it passes, you have a regression test that prevents this bug from returning.

Common Debugging Patterns

Pattern: Type Error Investigation

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.

Pattern: Race Condition Analysis

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.

Pattern: Build Error Cascade

When you have many build errors, do not fix them one by one:

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.

This is the TDD-style workflow that Steve Sewell at Builder.io popularized: let the agent run the build, see errors, fix them, and iterate until everything passes — all automatically when auto-run is enabled.

When This Breaks

The “fix-break-fix” loop. You are skipping Phase 1 (investigation). Go back to Ask mode, understand the system, then make one targeted change.

Agent “fixes” the test instead of the code. Explicitly say: “The test is correct. The implementation is wrong. Fix the implementation to make the test pass.”

Debug mode logs do not capture the issue. The bug may be in a different part of the call chain than expected. Ask the agent to add logging more broadly, or reproduce the bug multiple times to capture intermittent behavior.

Too many errors to fix at once. Triage: fix compile errors first (they block everything else), then runtime errors, then logic errors. Use the build error cascade pattern above.

What’s Next

• Testing Patterns — Writing tests that prevent bugs from recurring
• Refactoring Strategies — Cleaning up code after bug fixes
• Review Workflows — Catching bugs before they reach production