Debugging and Error Recovery skill for Claude Code: find the root cause, then fix it

• Stop, keep the evidence, diagnose, fix the root cause, guard, then resume

  When anything unexpected happens, the agent stops adding features and does not push past a failing test or broken build.

  Stop-the-line rule

• Make the failure happen reliably; tree for timing, environment and state bugs

  Runs the failing test alone and verbosely. If it cannot reproduce, it gathers logs and environment details.

  Runs code · Step 1: Reproduce

• Narrow down which layer fails; use git bisect for regressions

  Checks UI, API, database, build tooling, external service or the test itself. Bisect finds the commit that introduced a bug.

  Runs code · Step 2: Localize

• Strip the case to the smallest input and code that still fails

  A minimal reproduction makes the root cause obvious.

  Step 3: Reduce

• Fix why it happens, not where it shows up

  Example: fix the query that makes duplicates instead of deduplicating in the UI.

  Write · Step 4: Fix the root cause

• Write a test that fails without the fix and passes with it

  Every fix gets a regression test.

  Write · Step 5: Guard against recurrence

• Run the specific test, the full suite and the build

  Uses npm commands as the example; substitute your project's own.

  Runs code · Step 6: Verify end to end

• Decision trees for test failures, build failures and runtime errors

  Short trees for common cases such as type errors, import errors, CORS and white screens.

  Error-specific triage

• Treats logs and stack traces as data and asks before following steps in them

  If an error says to run a command or visit a URL, the agent shows it to you instead of acting.

  Untrusted error output

• Under time pressure, use a safe default with a warning or degrade gracefully

  The examples show a missing config value falling back to a default with a console warning, and a chart that shows an empty or error state instead of crashing.

  Write · Safe fallback patterns

• Add logging only when it helps, and remove it when done

  Add it when you cannot localize the failure or the issue is intermittent. Remove it once tests guard the fix, and always remove logs that hold sensitive data. Error boundaries and API error logging may stay.

  Write · Instrumentation guidelines

Watch out for

• It runs your tests, builds and git bisect

  The steps run npm test, npm run build, npm run dev and git bisect as examples. Work on a branch so you can reset easily.

• It is told to distrust error output

  The skill says not to run commands or open URLs found in error messages without your confirmation. Still read what it proposes before approving.