debugging-and-error-recovery

Debugging and Error Recovery

Where debug is a tight four-phase loop for one already-identified bug, this skill is the surrounding policy: what to do the instant something breaks, which triage tree applies to which failure class, and two extra practices that class-specific triage requires — bisection for regressions and safe-fallback design for degraded operation.

The stop-the-line rule

The instant something unexpected happens:

1. STOP adding features or making changes
2. PRESERVE evidence (error output, logs, repro steps)
3. DIAGNOSE using the triage tree for this failure class
4. FIX the root cause
5. GUARD against recurrence
6. RESUME only after verification passes

Don't push past a failing test or broken build to work on the next feature — errors compound, and an unfixed bug in step 3 makes everything built on top of it wrong too.

Triage trees by failure class

Test failure:

Did you change code the test covers?
├── YES → is the test or the code wrong?
│         ├── Test outdated → update the test
│         └── Code has a bug → fix the code
├── Changed unrelated code → likely a side effect: check shared state, imports, globals
└── Test was already flaky → check timing issues, order dependence, external dependencies

Build failure: type error → read it, check types at the cited location; import error → confirm the module exists and paths/exports match; config error → check build config syntax/schema; dependency error → check the manifest, reinstall; environment error → check runtime version/OS compatibility.

Runtime error: TypeError/nil dereference → trace where the value should have been set, not just where it was used; network/CORS error → check URLs, headers, server CORS config; render error/blank screen → check the error boundary, console, component tree; wrong behavior with no error → add logging at key points, verify data at each step.

Reproducing the non-reproducible

Cannot reproduce on demand:
├── Timing-dependent? → add timestamps around the suspected area; widen race windows with artificial delays; run under load to raise collision probability
├── Environment-dependent? → compare runtime/OS/env vars; compare data shape (empty vs populated); reproduce in CI where the environment is clean
├── State-dependent? → check for leaked state between tests/requests (globals, singletons, shared caches); run the scenario isolated vs. after other operations
└── Truly random? → add defensive logging at the suspected site; alert on the specific error signature; document conditions and revisit when it recurs