Debugging checklist

When something breaks and I have no idea why, I run through this list before touching any code. It turns panic into a process.

1. Reproduce it reliably

A bug you cannot trigger on demand is a bug you cannot fix with confidence. Find the exact steps first. If it is intermittent, note what differs between the times it happens and the times it does not.

2. Read the actual error

The whole message, and the whole stack trace, not just the first line. The answer is genuinely in there more often than you would expect. Note the file and line it points to.

3. Question your assumptions

The bug lives in the gap between what you think the code does and what it actually does. Do not assume a value is set, a function was called, or a branch was taken. Verify it.

console.log('reached checkout with', { cart, user });

4. Narrow the search space

Bisect the problem. Comment out half the code, or git bisect across commits, to find where working turns into broken. Halving the space each time beats reading everything.

5. Change one thing at a time

If you change five things and the bug goes away, you have learned nothing about which one mattered, and you may have added two new bugs. One change, one test.

6. Check the boring causes first

• A typo in a name or key
• A stale cache or an old build
• The wrong environment or config file
• Something not saved, or the server not restarted
• An off-by-one or a null you did not expect

7. Explain it out loud

Rubber-duck it. Describe the problem line by line to a colleague, or to a literal rubber duck. Saying it forces you to slow down, and you will often spot the flaw mid-sentence.

8. When you fix it, understand why

A fix you do not understand is a coincidence. Make sure you know why the change works, or the bug will come back wearing a different hat.