spencerpauly/awesome-cursor-skills/systematic-debugging

Systematic Debugging

Debug methodically instead of randomly changing code.

The Process

1. Reproduce

Before anything else, reproduce the bug reliably:

• Get the exact steps to trigger the issue
• Note the expected vs actual behavior
• Confirm it happens consistently (not intermittent)
• Record the environment (OS, Node version, browser, etc.)

If you can't reproduce it, you can't fix it. Ask for more details.

2. Isolate

Narrow down where the bug lives:

Binary search the codebase:

• Comment out half the system → does the bug persist?
• If yes, the bug is in the remaining half → repeat
• If no, the bug is in the commented-out half → repeat

Git bisect:

git bisect start
git bisect bad          # current commit is broken
git bisect good <sha>   # this commit was working
# Git checks out the midpoint — test it
git bisect good         # or git bisect bad
# Repeat until it finds the first bad commit
git bisect reset        # when done

Isolate by layer:

• Is it frontend or backend? (Check network tab)
• Is it the database? (Query directly)
• Is it the API? (curl the endpoint)
• Is it the component? (Render it in isolation)

3. Hypothesize

Form a specific, testable hypothesis:

• "The bug is caused by X because Y"
• Not "something is wrong with the data"
• Good: "The userId is null because the auth middleware doesn't run on this route"

4. Test the Hypothesis

Write the smallest possible test that proves/disproves your hypothesis:

• Add a console.log or breakpoint at the suspected location
• Check the value of the suspected variable
• If your hypothesis is wrong, go back to step 3 with new information
• If it's right, you've found the bug

5. Fix and Verify

• Apply the minimal fix
• Verify the original reproduction steps no longer trigger the bug
• Check for regressions — did the fix break anything else?
• Write a test that would have caught this bug

Debugging Tools

Common Bug Patterns

• Off-by-one: Array indices, pagination, date ranges
• Null/undefined: Missing optional chaining, uninitialized state
• Race condition: Async operations completing in unexpected order
• Stale closure: React useEffect/useCallback capturing old values
• Type coercion: == vs ===, string vs number comparisons
• Missing await: Forgetting await on async functions
• Environment mismatch: Works locally, fails in CI/prod due to different env vars or versions

Rules

• Never guess — always verify with evidence
• Fix the root cause, not the symptom
• If you've spent 15 minutes without progress, step back and re-isolate
• Document what you tried so you don't repeat failed approaches