debugging-and-error-recovery

Start by reproducing the failure reliably, then localize which layer is failing, reduce to a minimal failing case, and fix the root cause rather than the symptom. Finish by adding a regression test that fails without the fix and verifying the full suite passes.

Use git bisect to binary-search the commit history. Mark the current commit as bad and a known working commit as good, then run your failing test at each midpoint with git bisect run to automatically identify the offending commit.

Classify whether it is timing-dependent, environment-dependent, state-dependent, or truly random. Add timestamps and logging around the suspected area, compare environments and Node versions, check for leaked shared state, and set up alerts for the error signature.

Symptom fixes mask the underlying issue, so the bug resurfaces elsewhere and compounds with later changes. Asking why the failure happens until reaching the actual cause, such as fixing a faulty query instead of deduplicating in the UI, prevents recurrence.

Remove instrumentation once the bug is fixed and a regression test guards against recurrence, or when logs are only useful during development. Always remove logs containing sensitive data, but keep permanent instrumentation like error boundaries and API error logging.