Finding and fixing bugs

When something breaks, "fix this" is rarely enough. With 4RGE agents, the reliable path is the same as good engineering — just faster:

Symptom → repro → evidence → narrow fix → verify.

This lesson shows how to run that loop with an agent so you fix the root cause, not the loudest symptom or the most confident-sounding patch.

What this page is for

Who this page is for

The debug loop in five moves

You stay in control at every step: the agent investigates and drafts; you accept diffs and decide when the bug is actually gone.

Write a debugging brief

You do not need a novel. You do need facts the agent cannot invent.

Example you can paste and edit:

The /checkout endpoint returns 500 intermittently.
Repro: POST /checkout with an empty cart on staging.
Stack trace: TypeError: cannot read 'total' of undefined at cart.ts:42
Expected: 400 with { error: "empty_cart" }
Actual: 500 with no body
Run: pnpm test apps/web -- checkout.test.ts

Point at the failing test or file with @ when you know it — Prompting.

Reproduce before you fix

If you cannot reproduce it, say so — and say what you did try.

Repro is how you and the agent know the bug is gone — not just "looks fine in chat."

Let the agent investigate

Give the agent room to read, search, and run — that is what Tool calling is for. A strong first message asks for ranked hypotheses after reviewing the evidence, not a patch from memory.

For unfamiliar code, a short explore pass first saves wrong fixes — Understanding your codebase.

On desktop, Run and Debug (breakpoints) still pairs well with agent investigation when you need to pause execution. For cloud runs, follow the run stream and Diff tab when reviewing what changed.

Example debug prompts

Copy, edit, and paste — attach @ files when you know them.

First message (investigate, don't patch yet):

Bug: POST /checkout with empty cart returns 500 on staging.
Repro: POST /checkout with {} cart body.
Evidence: TypeError at cart.ts:42 — cannot read 'total' of undefined.
Expected: 400 { error: "empty_cart" }.
 
Before changing code: list the 3 most likely causes in order, then propose
the smallest check to confirm #1. Run: pnpm test apps/web -- checkout.test.ts

After cause is confirmed (narrow fix):

Cause confirmed: mergeCart assumes items[0] exists when cart is empty.
Fix only cart.ts and checkout.test.ts — guard empty cart before reading total.
No refactors outside that path. Re-run checkout.test.ts when done.

Verify (prove the bug is gone):

1. checkout.test.ts must pass (including new empty-cart case).
2. Run pnpm test apps/web -- checkout.
3. Summarize what changed in one sentence — I'll merge if green.

When the guess was wrong (reset):

Repro still fails after the last patch. Revert speculative edits in cart.ts.
Add one log at mergeCart entry showing cart shape, re-run checkout.test.ts,
and restart with a new hypothesis — don't widen scope yet.

For review after the fix lands, see Reviewing and testing code.

Fix in small steps

Prefer the smallest change that addresses the confirmed cause.

If the agent proposes a large rewrite for a small bug, ask it to narrow — same as you would with a teammate.

Verify the fix

"Sounds fixed" is not verification.

Run the narrow test before the full suite — it saves time and keeps the agent focused.

When checks pass and repro no longer fails, you decide merge — same as any other change. For a second pass on the diff, see Reviewing and testing code.

What good debugging looks like

When the guess is wrong

If the third "fix" still fails repro, stop widening:

1. Revert speculative edits (checkpoint, Git, or discard)
2. Add evidence — new log line, failing test output, or clearer repro
3. Restart with a tighter brief — or a fresh message if context is noisy — Context

That beats ten follow-up messages on the wrong theory — Working with agents.

Habits that work

1. Paste the stack trace or test output — do not paraphrase errors from memory.
2. State expected vs actual — removes ambiguity.
3. Name one command to run — agent and you agree on green.
4. Fix the failing test first — then expand scope.
5. Keep the diff small — review like any human PR.
6. Use plugins when logs live elsewhere — e.g. "query our error tracker for checkout 5xx" if you have that integration — Tools.

Where to go next

Questions about finding and fixing bugs?