Debug

No fix without a root cause. A change you can't explain is a new bug.

1. Reproduce

• Get the exact error text, inputs, environment, version and time.
• Make it fail on demand. Shrink to the smallest input/test that fails.
• Can't reproduce? Add logging at the boundaries and wait for evidence; do not guess.

2. Isolate

• What changed? git log / deploy history / dependency diffs / config / data.
• Bisect: git bisect for regressions; comment out halves for big code paths.
• Compare a working case with the failing one; the difference is the clue.
• Check boundaries first: inputs, network, env vars, time zones, permissions, caches, concurrency.

3. Hypothesize and test

• Write the hypothesis down: "X fails because Y, so if I do Z we'll see W."
• Change one variable per experiment. Revert experiments that disprove it.
• After three failed hypotheses, stop and re-read the code path end to end; your model of the system is wrong somewhere.

4. Fix

• Fix the cause at the right layer, not where the symptom shows.
• Smallest change. No drive-by refactors.
• Search for the same pattern elsewhere; fix or list siblings.

5. Prove

• Write a test that fails before the fix and passes after.
• Run the full relevant suite, not just the new test.
• In the report: symptom → root cause → fix → evidence → anything not covered.

Common culprits

Symptom	Look at
Works locally, fails in prod	env vars, build flags, data volume, region/time zone, caching, permissions
Flaky test	shared state, time, ordering, network, unawaited promises
Started after deploy	the diff, dependency bumps, migrations, config
Only some users	roles, tenant data, locale, browser, feature flags
Intermittent 500s	timeouts, pool exhaustion, rate limits, retries

Customize for your project

Where logs live ({{LOGS}}), how to get prod-like data safely, and the test command ({{VERIFY_COMMAND}}).