debugging

name	debugging
description	Systematically investigate and fix bugs, errors, or unexpected behavior. Use when the user reports a bug, shares an error/stacktrace, or asks why something isn't working.

Debugging Process

Step 1 — Reproduce First

Before theorizing, confirm the bug is reproducible.

• What is the exact input/action that triggers it?
• Does it happen consistently or intermittently?
• What environment? (OS, runtime version, config)

Step 2 — Read the Error

If there's a stacktrace or error message:

• Read it top to bottom — the root cause is usually at the bottom
• Identify the exact file, line, and function where the error originates
• Distinguish between the throw site and the propagation chain

Step 3 — Form Hypotheses (max 3)

List the most likely causes ranked by probability. For each:

• What assumption would have to be wrong for this to be the cause?
• What's the fastest way to confirm or rule it out?

Step 4 — Investigate Systematically

• Add targeted logging or print statements around the suspect area
• Use binary search: comment out half the code to isolate
• Check recent changes — git log -10 --oneline, git diff HEAD~1
• Verify inputs at every layer — don't assume upstream data is correct

Step 5 — Fix & Verify

• Fix the root cause, not the symptom
• Confirm the fix resolves the original issue
• Check for related code paths that might have the same bug
• Add a regression test if the bug had no test coverage

Common Traps

• Off-by-one errors in loops or slices
• Null/undefined handling missing at boundary
• State mutation where immutability was assumed
• Race condition in async code
• Config or env var missing in a specific environment