Debug anything: find the cause and fix it for good

Use this first, when all you know is that something is broken.

Something is broken and I need help writing a clear bug report before we try to fix it. What I see: [DESCRIBE WHAT IS HAPPENING]. Interview me one question at a time until you know: 1. What I expected to happen 2. What actually happens, word for word if there is an error 3. The exact steps to make it happen 4. Whether it happens every time or only sometimes 5. When it started, and what changed around then 6. Where it happens: which device, browser, operating system, or only on the live site Then write the bug report in that shape, plus one line saying which part of the system you suspect and why. Mark that line as a guess.

Swap the highlighted parts for your own words.

Tip

• Paste the finished report into Claude Code as the start of the next prompt.

Use this before anyone tries a fix.

Here is the bug: <bug> [PASTE THE BUG REPORT] </bug> Do not fix anything yet. Your job is to make the bug happen on demand. 1. Read the code involved. 2. Write the smallest test or script that triggers the bug. Prefer a test in the project's existing test setup. 3. Run it and confirm it fails in the same way the bug report describes. 4. Show me the exact command and its output. If you cannot make it fail, tell me what you tried and what extra information would help. Do not move on to a fix until we have a failing test or script.

Swap the highlighted parts for your own words.

Tip

• Keep the command that triggers the bug. Every later step uses it to check progress.

Use this once the bug reproduces.

The bug reproduces with: [THE COMMAND FROM THE LAST STEP]. Read the code on the path from the input to the failure. Then list three to five possible causes. For each cause give: - What would be going wrong - Evidence for it from the code or the error - Evidence against it - The cheapest check that would confirm or rule it out - How likely it is, as a rough percentage Rank them from most to least likely. Then run the cheapest useful check for the top cause, show me the result, and update the ranking. Keep going down the list until one cause is confirmed with evidence. Tell me before you change any real code.

Swap the highlighted parts for your own words.

Tip

• If every cause gets ruled out, the bug is somewhere you have not looked yet. Ask Claude to widen the search to config files, data and outside services.

Use this when you have a long error message and do not know where to look.

Explain this error to me. I am [YOUR LEVEL] with [LANGUAGE OR FRAMEWORK]. <error> [PASTE THE FULL ERROR AND STACK TRACE] </error> 1. Say in one sentence what went wrong. 2. Point to the line in the trace where my code was running when it failed, and which lines belong to libraries I did not write. 3. Explain the error type and its usual causes. 4. Say what to check first, second and third. In Claude Code, open the files from my code in the trace and look at the real lines before you answer. In the Claude app, say what you are assuming about the code you cannot see.

Swap the highlighted parts for your own words.

Tip

• Paste the whole trace. The useful line is often in the middle.

Use this when reading the code is not enough and you need to watch the values change.

I need to see what the code is doing when this bug happens: [SHORT DESCRIPTION]. Add temporary logging that prints: 1. The input as it enters [THE FUNCTION OR AREA]. 2. The value at each decision point (each if or loop that matters). 3. What is sent to and received from any outside service or database. 4. The output just before the failure. Rules: - Start every log line with DEBUG-TEMP so we can find and remove them later. - Never print passwords, keys or full personal data. Print a short preview or the length. Then run the reproduce command, show me the log output, and tell me what it shows. When we are done, remove every DEBUG-TEMP line and confirm none are left.

Swap the highlighted parts for your own words.

Tip

• Ask Claude to search for DEBUG-TEMP before you commit, to be sure the logging is gone.

Use this when something used to work and you do not know which change broke it.

This used to work and now it does not. It worked at [A COMMIT, TAG OR DATE WHEN IT WORKED]. It is broken now. Use `git bisect` to find the commit that broke it. 1. First, write a small script that exits with 0 when the bug is absent and 1 when it is present. Base it on the reproduce command: [THE COMMAND]. If a commit cannot be built or tested, the script should exit with 125 so bisect skips it. 2. Test the script on the current code and on the good commit, and show me both results. 3. Run `git bisect start`, mark the current commit bad and the old one good, then run `git bisect run` with the script. 4. When it finishes, show me the first bad commit, its message and what it changed. 5. Run `git bisect reset` to put the code back where it was. Then explain which part of that commit causes the bug.

Swap the highlighted parts for your own words.

Tip

• Bisect needs your project in git, the tool that records versions of your code, with a history of commits. It checks the middle commit, then halves the search each time, so even 1,000 commits take about 10 checks.

Use this once a cause is confirmed with evidence.

We confirmed the cause: [THE CONFIRMED CAUSE AND THE EVIDENCE]. Before you change code: 1. Trace the chain from the original mistake to the error we saw. Keep asking why until you reach the first thing that went wrong. Explain the chain in a few lines. 2. Search for other places in the code with the same mistake. 3. Propose the fix at the first thing that went wrong, and tell me what it changes. Then make the fix. The fix should correct the cause where it starts. Keep error handling honest: errors should still be reported, tests stay as they are, and checks stay switched on. Run the reproduce command and the full test suite, and show me the output. If the true fix is large or risky, tell me and offer a smaller safe fix for now, clearly labelled as temporary.

Swap the highlighted parts for your own words.

Tip

• Wrapping code in a try and catch that hides the error makes the symptom go away and keeps the bug. Ask "what happens to the error now?" if a fix looks like that.

Use this after the fix, so the same bug can never come back unnoticed.

Write a regression test for the bug we just fixed: a test that fails if the bug ever returns. 1. Name the test after the behaviour, such as "keeps the basket total when a coupon is removed". 2. Make it use the smallest input that triggered the bug. 3. Prove the test works. Temporarily undo only the fix with `git stash push --` followed by the files the fix changed, leaving the test file out. Run the test and show it failing. Then run `git stash pop` to bring the fix back, run the test again and show it passing. If the fix is already committed, revert it in a scratch branch for this check, and tell me what you did. 4. Run the whole test suite and show the result. If the reproduce test from earlier already does this job, tidy it into a proper test and say so.

Tip

• Step 3 shows the test can catch the bug. Keep that step, even when you are in a hurry.

Use this when the bug only happens on the live site, a teammate's computer or in automated tests.

This works on my computer but fails on [WHERE IT FAILS]. The error there is: <error> [PASTE THE ERROR OR LOGS FROM THERE] </error> List the differences between my setup and that one that could cause this. Check in this order: 1. Versions: the language, packages and the lockfile, the file that pins exact package versions 2. Environment variables and secrets that are set locally but missing there 3. Data: different database contents, empty tables, missing files 4. Operating system: file path style, letter case in file names, line endings 5. Timing and network: slower responses, blocked outside calls, time zone 6. Build steps that run differently there For each, say how to check it and what command or setting to look at. Read the project's config and deploy files before answering.

Swap the highlighted parts for your own words.

Tip

• Never paste live secrets or passwords into the chat. Paste the names of the variables only.

Use this for flaky tests or bugs you cannot trigger every time.

This bug happens only sometimes: [DESCRIPTION]. Roughly how often: [FOR EXAMPLE 1 IN 10 RUNS]. 1. Write a script that runs the failing test or action 50 times and counts the failures. Show me the count. 2. Read the code for things that make results vary: timers, random values, the current date, the order of items, two things running at once, shared state between tests, and network calls. 3. List the likely causes ranked, with the evidence for each. 4. Try to make it fail every time by forcing the suspected condition, such as a fixed delay or a fixed order. Show the result. Once it fails every time, stop and tell me. We will fix it with the normal steps.

Swap the highlighted parts for your own words.

Tip

• Adding a retry can make a flaky test pass and leave the bug in place. Find the cause first.

Use this when Claude has tried twice and the bug is still there.

We have tried to fix this twice and it is still broken. Before we go on, write a handover note for a fresh session. The note must include: 1. The bug and the exact command that reproduces it 2. Every cause we checked, and what ruled it out 3. Every fix we tried, and what happened 4. What we know for certain and what we are still assuming 5. The best next step Save it to DEBUG-NOTES.md. Then undo any experimental changes that did not help, and confirm the code is back to its starting state apart from useful tests.

Tip

• Then type /clear and start the new session with "Read DEBUG-NOTES.md and continue." A clean session with a better starting prompt usually does better than a long one full of failed attempts.