debugging-and-error-recovery

Reproduce the failure reliably first, 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 running the full suite to check for regressions.

Use git bisect: mark the current commit as bad and a known working commit as good, then test each midpoint checkout. You can automate it with git bisect run followed by your test command to identify the exact offending commit.

Classify it as timing-dependent, environment-dependent, state-dependent, or truly random. Add timestamps or artificial delays for race conditions, compare environments and data states, run scenarios in isolation, and set up logging or alerts to capture it when it recurs.

Symptom fixes mask the underlying issue, which 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.

Add instrumentation when you cannot localize a failure or the issue is intermittent, and remove it once the bug is fixed and guarded by tests. Keep permanent logging only for error boundaries, API error context, and key performance metrics, and never log sensitive data.