What do I need to prepare before starting?

The full stack trace verbatim (every frame — never summarize it), the exact request or input that reproduces the bug, and the project's root folder open in Claude Desktop so it can read the actual files the trace points to. The verbatim trace is the most important input; the exact frames are usually where the root cause is hiding. Diagnosis and the fix work entirely in Desktop — only running your project's test suite is a Power-Track step that wants a terminal-enabled session.

Why ask for a ranked list of causes instead of just the fix?

Because the first plausible-sounding fix is often the wrong one. Forcing a ranked hypothesis list before any code changes means you check the reasoning when it's still cheap prose — not after Claude has already produced a 200-line diff in the wrong direction. Read the list, confirm the right cause, then ask for the fix.

How do I make sure the fix is real and not just a workaround?

Ask for a regression test that fails on the current code and passes after the fix, before the fix is written. The red-to-green test is the receipt that the change addresses the root cause, not just the symptom. A confident explanation with no failing-then-passing test is still a guess.

What if I can't reproduce the bug to get a clean trace?

Start with "write the smallest script or test that reproduces this from the trace" — once it reproduces reliably, the rest of this playbook applies. For a Heisenbug that only appears under load or timing, ask Claude to add targeted logging around the ranked suspects, run again, and reason from the new output rather than guessing.

Trace a bug to its root cause and prove the fix

when to reach for this

It's a production incident: users report they get logged out at random, the person who wrote the auth flow left two months ago, and you have a stack trace, a request that triggers it, and a dozen plausible suspects. The trap is to start patching the first thing that looks wrong. This system makes you debug from evidence — diagnosis first, ranked by likelihood, then a fix you can prove with a test instead of a hopeful "that should do it."

gather this first

The full stack trace, verbatim — every frame, not "it crashes on login." Paste it straight into the chat in Claude Desktop. The exact frames are usually where the answer is.
The request, input, or steps that reproduce it — the smaller and more exact, the better.
The project's root folder open in Claude Desktop, so Claude can read the actual files the trace points to. (Power Track: launch claude from the project root if you prefer the terminal.)

the workflow

Diagnose before you patch — and rank the causes

Force a hypothesis list before any code changes. You want to sanity-check the reasoning while it's cheap prose, not after it's a 200-line diff.

you ask

Here's the full stack trace and the request that triggered it. Trace the logic end to end and give me the three most likely root causes, ranked, with the file and line for each and the reasoning. Don't fix anything yet.

what you get back A ranked list with auth/session.ts:142-style pointers and the why behind each — a stale TTL, a race on token refresh, a clock-skew check — so you're debugging from evidence, not vibes.

"Don't fix anything yet" is doing real work here. The diagnosis is the part you most need to check with your own judgment.
Confirm the real cause against the code

Pick the hypothesis that fits and make Claude prove it's the one — by pointing at the exact code path, not by asserting it.

you ask

Cause #2 looks right. Show me the exact code path that produces this bug — the lines that set the bad state and the lines that read it — and explain why the current behaviour is wrong.

what you get back A concrete walk from cause to symptom across the real files, so you understand the bug, not just the patch you're about to approve.
Fix it, and write the failing test first

A change without a test it turned green is a guess. Ask for the regression test that reproduces the bug, then the smallest fix that flips it. In Claude Desktop the change comes back as a visual diff you accept or reject right in the chat — read it before you accept.

you ask

Now add a test that fails on the current behaviour and passes once it's fixed, then make the smallest change that fixes it. Show me the diff before you touch anything else.

what you get back A failing-then-passing regression test plus a tight diff you can accept or reject in the file pane. The red-to-green test is the receipt that the fix addresses the bug, not just the symptom you described.
Run the real loop and read the diff

Let it run your actual suite and type-checker, feed back any red, and read every line before you approve. Running your project's test command is a Power Track step — it needs the terminal-enabled session (Claude Code in the terminal, or Desktop with command-running turned on). You're still the author of record.

you ask

Run the full test suite and the type-checker. If anything's red, fix it and show me what changed. Then give me the final diff to review.

what you get back A green suite and a reviewed diff — usually right, occasionally confidently wrong, which is exactly why you read it.

No terminal session handy? Run the suite yourself the way you normally would, paste any failures back into the Desktop chat, and let Claude reason from the real output — the loop is the same, you're just the one pressing enter.

make it your own

No reproduction yet: start with "write the smallest script or test that reproduces this from the trace" — once it reproduces, the rest of the system applies.
Heisenbug: ask it to add targeted logging around the ranked suspects, run again, and reason from the new output rather than guessing in the dark.
Make the fix the start of a safety net: the failing-then-passing test you wrote here is the first case of a real suite — when the module around the bug is thinly tested, hand it straight to the backfill-tests playbook so the next change in that file isn't another gamble. If the bug lives in a corner of a repo you don't know, point Claude at the CLAUDE.md you built in project-context first, and reach for a subagent on a wide hunt across many files so the deep dig doesn't crowd your main context (see the subagents feature).

watch out for

Paste the trace and input verbatim — don't summarize. "It crashes on login" throws away the exact frame that holds the answer.
Make it prove the fix — the failing-then-passing test is the receipt. A confident explanation with no red test it turned green is still a guess, and the diagnosis is the part you most need to check with your own judgment; you're the author of record on the merge.
Read the diff before you approve it. Treat its output like a PR from a fast, eager junior — usually right, occasionally wrong with total confidence.

you'll end up with You go from a random-looking bug to a root cause you understand and a fix backed by a regression test — debugged from evidence in an afternoon, not guessed at over two days.

Questions people ask

What do I need to prepare before starting?: The full stack trace verbatim (every frame — never summarize it), the exact request or input that reproduces the bug, and the project's root folder open in Claude Desktop so it can read the actual files the trace points to. The verbatim trace is the most important input; the exact frames are usually where the root cause is hiding. Diagnosis and the fix work entirely in Desktop — only running your project's test suite is a Power-Track step that wants a terminal-enabled session.
Why ask for a ranked list of causes instead of just the fix?: Because the first plausible-sounding fix is often the wrong one. Forcing a ranked hypothesis list before any code changes means you check the reasoning when it's still cheap prose — not after Claude has already produced a 200-line diff in the wrong direction. Read the list, confirm the right cause, then ask for the fix.
How do I make sure the fix is real and not just a workaround?: Ask for a regression test that fails on the current code and passes after the fix, before the fix is written. The red-to-green test is the receipt that the change addresses the root cause, not just the symptom. A confident explanation with no failing-then-passing test is still a guess.
What if I can't reproduce the bug to get a clean trace?: Start with "write the smallest script or test that reproduces this from the trace" — once it reproduces reliably, the rest of this playbook applies. For a Heisenbug that only appears under load or timing, ask Claude to add targeted logging around the ranked suspects, run again, and reason from the new output rather than guessing.