Skill · Coding
systematic-debugging
Hunts down bugs whose cause isn't obvious: flaky or intermittent failures, 'works locally but fails in CI', regressions nobody can place, or a fix that didn't stick. Makes the bug reproduce reliably, ranks hypotheses, narrows with git bisect or input halving, confirms the cause before changing code, and proves the fix with a regression test. Use when a test is flaky, it 'works on my machine', something broke after an upgrade or merge, a first fix didn't work, or when asked to find the root cause.
The skill itself. Agents read the name and description first and load the rest only when a task matches.
systematic-debugging/SKILL.md
---
name: systematic-debugging
description: "Hunts down bugs whose cause isn't obvious: flaky or intermittent failures, 'works locally but fails in CI', regressions nobody can place, or a fix that didn't stick. Makes the bug reproduce reliably, ranks hypotheses, narrows with git bisect or input halving, confirms the cause before changing code, and proves the fix with a regression test. Use when a test is flaky, it 'works on my machine', something broke after an upgrade or merge, a first fix didn't work, or when asked to find the root cause."
---
# Systematic debugging
For bugs where the cause isn't obvious. If the error message already points at the faulty line, write a failing test, fix it and skip the rest of this.
## Steps
1. Write down observed vs expected, the exact error text, and the exact command, request or click path that shows it.
2. Make it reproduce reliably.
- Intermittent: run the failing test 20 times in a loop and record how many runs fail. Run it alone, then with the full suite, then in a different order, to expose shared state between tests.
- Works locally, fails in CI (or the reverse): list the differences and check each one: runtime and dependency versions (is the lockfile used?), env vars, time zone and locale, OS and filesystem case sensitivity, CPU count and test parallelism, network access, seed data and secrets. Copy CI's setup locally (same versions, TZ=UTC, the same env vars) until it fails here too.
- Can't reproduce at all: ask for logs, versions, the exact input and steps. Don't guess a fix.
3. Shrink: cut the input and steps down to the smallest case that still fails.
4. Hypothesize: list two to four possible causes, ranked by likelihood, each with the evidence for it and the check that would rule it out.
5. Narrow, one check at a time, recording each result:
- Regression with a known-good commit: `git bisect start <bad> <good>`, then `git bisect run <test command>` (the command must exit non-zero when the bug is present), then `git bisect reset`.
- Large input or config: halve it and keep the half that still fails.
- Otherwise: add targeted logging or inspect values in a debugger at the point the hypothesis predicts.
6. Confirm the cause: you have it when you can explain the full chain from cause to symptom and predict a change that makes the bug go away.
7. Write a regression test that fails on the current code every time. For flaky bugs, control the cause in the test (fixed clock, seeded randomness, forced ordering) so it fails reliably. Run it and watch it fail.
8. Fix the root cause, not the symptom. A try/catch, a null check, a longer timeout or a retry that hides the error is not a fix unless the cause really is an expected condition.
9. Verify: the regression test passes, the full suite passes, the original reproduction no longer fails. For an intermittent bug, rerun the loop with several times as many runs as it took to fail before. Remove temporary logging.
10. Report: symptom, root cause, how you found it, the fix, the test added, and the command output that shows it passing.
## Rules
- No fix before a confirmed cause.
- Change one thing at a time.
- After three hypotheses fail, stop guessing and re-gather data: reread the error, and check your assumptions about versions, environment, config and inputs.
- Never say "fixed" without command output that shows it.
- If the root cause is out of scope (a library bug, infrastructure), say so, apply a clearly labeled workaround, and note what the real fix would be.
## Example output
```
Symptom: checkout.test.ts fails in CI 1 run in 6; never locally.
Cause: test relies on local time; CI runs in UTC, so "today" flips at 00:00 UTC. Found by running locally with TZ=UTC (fails 20/20 between 00:00 and 01:00 local).
Fix: compare dates in UTC in isExpired().
Test: "treats a coupon ending today as valid in any time zone" with a fixed clock; failed before, passes now.
Verified: 100 loop runs, 0 failures; full suite 212 passed.
```