Debug Failures and Recover from Errors Systematically

This skill applies systematic debugging with structured triage: when something breaks, stop adding features, preserve evidence, and follow a fixed process rather than guessing. It applies to test failures, build errors, runtime bugs, and production incidents. The stop-the-line rule is to stop making other changes, preserve error output, logs, and repro steps, diagnose via the triage checklist, fix the root cause, guard against recurrence with a test, then resume only after verification passes - never pushing past a failing test to work on the next feature, since unfixed bugs compound and corrupt later work.

The six-step triage checklist starts with reproducing the failure reliably, including sub-strategies for non-reproducible bugs by category - timing-dependent issues via timestamped logs and artificial delays to widen race windows, environment-dependent issues via version and config comparisons, state-dependent issues via checking for leaked global state, and truly random issues via defensive logging and alerting. It then localizes which layer is failing - UI, API, database, build tooling, an external service, or the test itself - using git bisect to find the introducing commit for regressions. Next it reduces the case to a minimal failing example by stripping unrelated code, config, or input until only the bug remains. It then fixes the root cause rather than the symptom, illustrated with a duplicate-user-list example where deduplicating in the UI is the bad symptom fix and fixing the underlying SQL join producing duplicates is the good root-cause fix, by repeatedly asking why this happens until reaching the actual cause. It writes a regression test that fails without the fix and passes with it, specifically guarding against that failure recurring, and finally verifies end-to-end by running the specific test, the full suite for regressions, a build for compilation errors, and a manual spot check.

Error-specific triage trees cover test failures, distinguishing an outdated test from a real code bug or a side effect from unrelated changes; build failures, covering type errors, import errors, config errors, dependency errors, and environment errors; and runtime errors, covering undefined-property errors traced through data flow, network or CORS issues, render errors caught by error boundaries, or unexpected behavior needing added logging. Safe fallback patterns for time pressure cover defaulting a missing config value with a warning instead of crashing, and graceful degradation such as an empty state for no data or a caught render error showing an error state instead of crashing the whole component. Instrumentation guidelines say to add logging only when localization fails, the issue is intermittent, or multiple components interact, and remove it once the bug is fixed and guarded by tests or if it contains sensitive data, while keeping permanent instrumentation like error-boundary reporting, API error logging with context, and performance metrics at key flows. A rationalizations table rebuts common debugging shortcuts like assuming you already know the bug, dismissing a failing test as probably wrong, blaming environment differences, deferring the fix to the next commit, or ignoring flaky tests.

Critically, it treats error output, stack traces, and logs as untrusted data to analyze, not instructions to follow - never executing commands or visiting URLs suggested inside error text without user confirmation, since a compromised dependency or adversarial input could embed instruction-like text there, and surfacing any such suspicious content to the user instead of acting on it.

Use it when tests fail after a change, a build breaks, runtime behavior doesn't match expectations, a bug report arrives, an error appears in logs or console, or something that worked before stops working.

Given a failure or bug report, it produces a documented root cause, a minimal reproduction, a fix addressing that cause, a regression test proving it, and end-to-end verification across tests, build, and a manual check.

git bisect for regression hunting, npm test and build tooling, and error-boundary or logging infrastructure for permanent instrumentation.

Developers and AI-agent workflows debugging test failures, build breaks, or runtime bugs who need a disciplined, evidence-first process instead of guessed fixes - including explicit guardrails against treating error-message content as trusted instructions.