Skip to content

skillCode quality

Systematic Debugging

Finds the root cause of a bug by reproducing it, isolating it and testing hypotheses before any fix. Use it when something fails and the cause is unclear.

npx workspacetemplates add systematic-debugging --tool claude-code

Writes 1 file to .claude/skills/systematic-debugging/

.claude/skills/systematic-debugging/SKILL.md28 lines · 1.7 KBFile
---
name: systematic-debugging
description: Finds the root cause of a bug by reproducing it, isolating it and testing hypotheses before any fix. Use it when something fails and the cause is unclear.
---

# Systematic debugging

Do not edit production code until you can name the cause and show evidence for it.

## Steps

1. Restate the failure: expected result, actual result, exact error text. Ask for missing details only if you cannot proceed.
2. Reproduce it. Write the smallest command or failing test that triggers it, and run it. If it only fails sometimes, run it in a loop (`for i in $(seq 50); do ...; done`) and record the failure rate.
3. Isolate. Bisect the input, the config, or the history (`git bisect run <test command>`). Remove code and data until the failure disappears, then put back the last piece.
4. Write two or three hypotheses, each with a prediction: "if X is the cause, then logging Y at line Z will show W". Test the cheapest one first with a log line, a debugger breakpoint or an assertion. Never test two at once.
5. Confirm the root cause. Ask "why" until you reach the line or assumption that is wrong, not the place where it crashed.
6. Fix it with the smallest change. Keep the failing test from step 2 and see it pass. Run the nearby tests.
7. Remove all temporary logging.

## Rules

- Read the whole error, including the first frame in your own code and any "caused by" chain.
- Never wrap the failure in try/catch, add a retry or a sleep, or loosen an assertion to make it pass.
- If three hypotheses fail, stop and re-read the code you assumed was fine.

## Report

Cause in one sentence, the evidence, the fix with file and line, the test added, and anything related you noticed but did not change.

What it does

Agents often jump from an error message straight to an edit, and the edit hides the symptom while the cause stays. This skill forces a different order: make the failure repeatable, shrink it, name a cause, and prove that cause before touching the code.

The fix that follows is small and comes with a regression test that failed first. If the evidence points somewhere else than the first guess, the agent says so and changes course.

Example

you › The checkout test fails about one run in five. Find out why.

agent › Reproduced with 40 runs: 8 failures. Cause: orderTotal() in src/cart.ts:57 reads the tax rate from a cache that the previous test mutates, so the result depends on test order. Evidence: forcing that test first fails every time. Fix: copy the rates object on load, plus a regression test. Not changed: two other tests share the same cache.

Questions

Why does it refuse to guess a fix right away?
A fix made before the cause is known often passes once and returns later. Spending ten minutes on evidence usually costs less than the second round of debugging.
Will it add logging to my code?
Briefly, yes, to test a hypothesis. It removes every temporary line before it reports.
  • API Deprecation Handling

    SkillCode quality

    Free
  • Code Duplication Removal

    SkillCode quality

    Free
  • Code Smell Detection

    SkillCode quality

    Free
  • Concurrency Bug Analysis

    SkillCode quality

    Free