Systematic Debugging
Reproduce → isolate → prove the cause → fix the root. Triages trivial bugs fast, goes deep only when needed. Ships drop-in instrumentation.
v1.0.0 · ~569 tokens · ⬇ 0 · Updated July 6, 2026
What it does
Root-cause method with a 30-second triage up front so simple bugs skip the ceremony. Reproduce reliably, bisect to locate, form a falsifiable hypothesis and instrument to prove it, fix the cause not the symptom, then add a regression test. Refuses random changes and 'fixing the test to pass'.
Example uses
Root-cause a production-only bug
Something works locally but fails in production, and changing things at random has not worked.
Our image-resize endpoint returns 500s in production but works locally with the same input files. Debug this systematically: get a reliable reproduction first, then bisect the differences — environment variables, memory limits, library versions — and prove the cause with evidence before proposing any fix.Reproduce an intermittent bug
A bug appears occasionally and 'cannot reproduce' has stalled the fix for weeks.
About one in every fifty checkout attempts, the cart total briefly shows $0 and then corrects itself. Nobody can reproduce it on demand. Make the flakiness reproducible first — control the timing and ordering around the price fetch — then isolate the smallest region that shows the bug and prove the root cause.Trace a silent data bug
The output is wrong but nothing throws, so there is no stack trace pointing anywhere.
Our nightly export job writes duplicate rows for some customers, with zero errors in the logs. Instrument the pipeline at each stage boundary, find where the duplication is introduced, and fix the cause rather than deduping the output. Finish with a test that reproduces the original bug so it can't come back.Install
# 1. Create the skill folder in your Claude setup mkdir -p ~/.claude/skills/systematic-debugging # 2. Download SKILL.md into it (or move the file you just downloaded) # → ~/.claude/skills/systematic-debugging/SKILL.md # 3. Claude Code auto-discovers it on next launch.
Inside the skill
---
name: systematic-debugging
description: Root-cause a bug methodically instead of guessing. Use when something is broken, failing, flaky, or behaving unexpectedly ("debug this", "why is this failing", "it works locally but not in prod"). Triages fast, then goes deep only if needed.
---
# Systematic Debugging
Guess-and-check wastes hours. Reproduce, isolate, prove the cause, then fix. Triage
first so trivial bugs don't get the full ceremony.
## Step 0 — Triage (30 seconds)
- Read the actual error + stack trace fully. The answer is often the first line you skimmed.
- Obvious typo / missing import / null on a named line? Fix it, move on. Not every bug needs the method.
- Otherwise → go systematic below.
## The method
1. **Reproduce reliably.** Find the smallest, deterministic trigger. A bug you can't
reproduce, you can't fix — you can only hope. If it's flaky, reproduce the flakiness
(loop it, control the timing/ordering).
2. **Locate.** Bisect the distance between "known good" and "observed bad": comment out
halves, add checkpoints, `git bisect` across commits. Narrow to the smallest region
that still shows the bug.
3. **Hypothesize + instrument.** State one falsifiable cause ("the list is empty because
the filter runs before the fetch resolves"). Add a log/breakpoint that would PROVE OR
DISPROVE it. Run. Let evidence, not vibes, confirm.
4. **Fix the cause, not the symptom.** Patch the root, not the place it surfaced. If you
find yourself special-casing the output, you're treating the symptom.
5. **Verify + guard.** Confirm fixed. Add a test that reproduces the original bug so it
can't return. Remove debug instrumentation.
## Instrumentation snippets (drop-in)
- Trace value + location: `console.log("[dbg] X @ handler", { x, type: typeof x })`.
- Prove ordering: log with timestamps at each async boundary.
- Catch the swallow: temporarily log inside every `catch` — silent catches hide bugs.
## Anti-patterns (refuse)
- Changing things at random hoping one sticks. If you don't know why a change would fix
it, you don't understand the bug yet.
- **"Fixing" the test to make it pass.** That hides the bug for the next person.
- Declaring victory on "it works now" without knowing WHY it broke — it'll be back.
Changelog
- v1.0.02026-07-03Initial clean-room write.
Frequently asked questions
Is Systematic Debugging free?
Yes. Systematic Debugging is free to download and MIT-licensed.
Where do I install Systematic Debugging?
Place the SKILL.md file in ~/.claude/skills/systematic-debugging/ and Claude Code auto-discovers it on next launch.
How many tokens does Systematic Debugging use?
About 569 tokens — it is designed to be token-lean.
We're developers and SaaS builders who use these tools daily in production. Every review comes from hands-on experience building real products — DealPropFirm, ThePlanetIndicator, PropFirmsCodes, and many more. We don't just review tools — we build and ship with them every day.
Written and tested by developers who build with these tools daily.