agent-skills-debugging-and-error-recovery

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

Run git bisect start, 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 whether it is timing-dependent, environment-dependent, state-dependent, or truly random. Add timestamps or artificial delays for race conditions, compare environments and data states, and set up logging or alerts to capture the error signature when it recurs.

Symptom fixes mask the underlying defect, which resurfaces elsewhere and compounds with later changes. Asking why the failure happens until reaching the actual cause ensures the fix is durable and the regression test guards the real issue.

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.