debugging-and-error-recovery

A structured debugging workflow applies step-by-step guidance: reproduce the failure, localize the failing component, reduce to a minimal repro, implement a root-cause fix, add a regression test, and verify end-to-end. This methodical progression prevents skipping critical diagnostic steps during incident triage.

Git bisect helps isolate regression commits by systematically narrowing down the failing code change. You reproduce the failure locally, use git bisect to find the introducing commit, create a minimal repro, fix the root cause, and add regression tests to prevent recurrence.

Debugging flaky tests requires targeted patterns including instrumenting the code to capture intermittent state, treating error output as untrusted data, and establishing reproducibility steps. Safe fallback patterns and monitoring are added to catch non-reproducible issues during regression investigations.

When triaging production incidents, treat error output as untrusted data and avoid blind execution of commands found in logs. Apply safety guardrails by verifying log contents, using structured triage checklists, and adding regression tests with monitoring to prevent recurrence after the root-cause fix.

Root-cause debugging applies to both development workflows and production incident triage. It handles test failures, build-time errors, flaky tests, and regression investigations by providing reproducibility steps, localization guidance, minimal repro creation, and end-to-end verification checklists across both contexts.