systematic-debugging
Debugs by evidence instead of guessing. Use whenever a test fails, behavior regressed, a bug is intermittent or environment-specific, or the user needs to find which commit introduced a defect, even if they only say "this is broken" or "why does this fail". Reproduces, isolates a
Install
npx skills add https://github.com/MehranQadirian/skills/tree/main/git/systematic-debugging
claude plugin marketplace add https://llmmart.ai/marketplace.json && claude plugin install mehranqadirian-skills@llmmart
git clone https://github.com/MehranQadirian/skills.git
The skills CLI installs just this skill, for any of its supported agents. Claude Code installs the whole mehranqadirian/skills collection as a plugin from our marketplace. Git is the plain clone.
README
systematic-debugging
A Claude skill that finds and fixes bugs with evidence: reproduce, isolate, prove, fix, then guard with a regression test.
What it does
- Follows an 8 step method from reproduction to recorded fix
- Uses
git bisect,blame,log -S,reflogandworktreeto locate regressions - Ships a tested
bisect_helper.shthat checks good and bad refs before bisecting - Gives instrumentation tips for shell and Python
- Measures flaky failure rates and compares environments
- Provides a bug report template
- Hands the fix to Commitsmith for the commit message
Try it
This test started failing last week. Find the commit that broke it.
This bug only happens on CI. Help me isolate it.
This test fails 1 in 10 runs. Measure it and find the cause.
Write a bug report for this crash.
Install
Claude.ai: zip this folder, then go to Settings > Capabilities > Skills > Upload.
Claude Code:
cp -r git/systematic-debugging ~/.claude/skills/
Structure
systematic-debugging/
├── SKILL.md skill instructions for Claude
├── scripts/
│ ├── bisect_helper.sh safe git bisect wrapper
│ └── flaky_runner.sh measure intermittent failure rate
├── references/
│ ├── bisect-playbook.md bisect details and hard cases
│ └── flaky-and-env.md flaky tests and environment diffs
└── templates/bug-report.md bug report template
Skill manifest
systematic-debugging
Debug by evidence, not by guessing. Each step narrows the search space until the root cause is proven and a regression test locks the fix.
systematic-debugging/
├── SKILL.md
├── scripts/
│ ├── bisect_helper.sh safe `git bisect run` wrapper with sanity checks and automatic reset
│ └── flaky_runner.sh run a command N times, report failure rate, save first failure log
├── references/
│ ├── bisect-playbook.md preconditions, exit codes, merge commits, skipping, after the hit
│ └── flaky-and-env.md flaky test causes, "works on my machine" checklist, delta debugging
└── templates/
└── bug-report.md report with evidence, root cause, regression test, verification
When to use
- A test fails or behavior regressed
- A bug is intermittent or environment-specific
- You need the exact commit that introduced a defect
Method
- Reproduce: build the smallest reliable failing case. If it is intermittent, measure the rate with
scripts/flaky_runner.sh. - Observe: collect logs, stack traces, inputs and versions.
- Hypothesize: write 2 to 3 candidate causes, ranked by likelihood, each with a test that would disprove it.
- Isolate: bisect history with
scripts/bisect_helper.sh, or shrink the input by halves. - Prove: confirm the root cause with a failing test or a printed fact. A theory without evidence is still a guess.
- Fix: change the minimum necessary.
- Guard: add a regression test that fails before and passes after the fix, then run the full suite.
- Record: put cause and fix in the commit message and fill
templates/bug-report.mdfor non-trivial bugs.
Choosing the isolation tool
| Situation | Tool |
|---|---|
| It worked before, you know a good commit | bash scripts/bisect_helper.sh <good> HEAD -- <test> |
| Which change touched this line | git blame -L 40,60 file then git log -p -- file |
| When did this string appear or vanish | git log -S "name" --oneline |
| Fails sometimes | bash scripts/flaky_runner.sh 50 -- <test> then references/flaky-and-env.md |
| Works here, fails there | env and dependency diff, clean git worktree |
| Lost work or odd HEAD | git reflog, git stash list |
| Large input triggers it | halve the input until minimal |
Details and edge cases: references/bisect-playbook.md.
Git-powered commands
git bisect start && git bisect bad HEAD && git bisect good v1.2.0
git bisect run /tmp/run_test.sh # keep the script outside the repo
git bisect reset
git blame -L 40,60 path/to/file
git log -S "functionName" --oneline
git reflog
git stash push -m "wip debugging"
git worktree add ../repro <commit>
Instrumentation tips
# Shell scripts
set -euxo pipefail
import logging
logging.basicConfig(level=logging.DEBUG, format="%(asctime)s %(threadName)s %(message)s")
# breakpoint() # drop into pdb at the suspicious line
Rules of thumb
- Change one variable at a time
- If you cannot reproduce it, you cannot claim to have fixed it
- One green run does not prove an intermittent bug is fixed; repeat it
- Verify that the code you edit is the code that actually runs
- Keep the bisect test script outside the repository, or old commits will not contain it
- After 30 minutes without progress, explain the problem in writing (rubber duck)
- Never commit a fix without a test or a documented manual proof
What to report back
| Field | Content |
|---|---|
| Root cause | one paragraph with the evidence that proves it |
| First bad commit | sha and subject, if bisected |
| Fix | files changed and why it is minimal |
| Regression test | file and name, shown failing before the fix |
| Residual risk | similar code paths checked or not |
Related skills
commitsmith: write the commit message for the fix, naming the root causepdf-processing: an example pipeline that benefits from verification-first debuggingmulti-agent-orchestration: trace handoff logs to find which agent produced a wrong result
Files (skills)
-
references
-
bisect-playbook.md 2.2 KB
Loading… -
flaky-and-env.md 2.4 KB
Loading…
-
-
scripts
-
bisect_helper.sh 2.4 KB
Loading… -
flaky_runner.sh 1.3 KB
Loading…
-
-
templates
-
bug-report.md 875 B
Loading…
-
-
README.md 1.5 KB
# systematic-debugging A [Claude skill](../../README.md) that finds and fixes bugs with evidence: reproduce, isolate, prove, fix, then guard with a regression test. ## What it does - Follows an 8 step method from reproduction to recorded fix - Uses `git bisect`, `blame`, `log -S`, `reflog` and `worktree` to locate regressions - Ships a tested `bisect_helper.sh` that checks good and bad refs before bisecting - Gives instrumentation tips for shell and Python - Measures flaky failure rates and compares environments - Provides a bug report template - Hands the fix to [Commitsmith](../commitsmith/) for the commit message ## Try it > This test started failing last week. Find the commit that broke it. > This bug only happens on CI. Help me isolate it. > This test fails 1 in 10 runs. Measure it and find the cause. > Write a bug report for this crash. ## Install **Claude.ai:** zip this folder, then go to Settings > Capabilities > Skills > Upload. **Claude Code:** ```bash cp -r git/systematic-debugging ~/.claude/skills/ ``` ## Structure ``` systematic-debugging/ ├── SKILL.md skill instructions for Claude ├── scripts/ │ ├── bisect_helper.sh safe git bisect wrapper │ └── flaky_runner.sh measure intermittent failure rate ├── references/ │ ├── bisect-playbook.md bisect details and hard cases │ └── flaky-and-env.md flaky tests and environment diffs └── templates/bug-report.md bug report template ``` -
SKILL.md 4.5 KB
--- name: systematic-debugging description: Debugs by evidence instead of guessing. Use whenever a test fails, behavior regressed, a bug is intermittent or environment-specific, or the user needs to find which commit introduced a defect, even if they only say "this is broken" or "why does this fail". Reproduces, isolates and proves the root cause, then locks the fix with a regression test. Uses git bisect, blame and reflog. --- # systematic-debugging Debug by evidence, not by guessing. Each step narrows the search space until the root cause is proven and a regression test locks the fix. ``` systematic-debugging/ ├── SKILL.md ├── scripts/ │ ├── bisect_helper.sh safe `git bisect run` wrapper with sanity checks and automatic reset │ └── flaky_runner.sh run a command N times, report failure rate, save first failure log ├── references/ │ ├── bisect-playbook.md preconditions, exit codes, merge commits, skipping, after the hit │ └── flaky-and-env.md flaky test causes, "works on my machine" checklist, delta debugging └── templates/ └── bug-report.md report with evidence, root cause, regression test, verification ``` ## When to use - A test fails or behavior regressed - A bug is intermittent or environment-specific - You need the exact commit that introduced a defect ## Method 1. **Reproduce**: build the smallest reliable failing case. If it is intermittent, measure the rate with `scripts/flaky_runner.sh`. 2. **Observe**: collect logs, stack traces, inputs and versions. 3. **Hypothesize**: write 2 to 3 candidate causes, ranked by likelihood, each with a test that would disprove it. 4. **Isolate**: bisect history with `scripts/bisect_helper.sh`, or shrink the input by halves. 5. **Prove**: confirm the root cause with a failing test or a printed fact. A theory without evidence is still a guess. 6. **Fix**: change the minimum necessary. 7. **Guard**: add a regression test that fails before and passes after the fix, then run the full suite. 8. **Record**: put cause and fix in the commit message and fill `templates/bug-report.md` for non-trivial bugs. ## Choosing the isolation tool | Situation | Tool | |-----------|------| | It worked before, you know a good commit | `bash scripts/bisect_helper.sh <good> HEAD -- <test>` | | Which change touched this line | `git blame -L 40,60 file` then `git log -p -- file` | | When did this string appear or vanish | `git log -S "name" --oneline` | | Fails sometimes | `bash scripts/flaky_runner.sh 50 -- <test>` then `references/flaky-and-env.md` | | Works here, fails there | env and dependency diff, clean `git worktree` | | Lost work or odd HEAD | `git reflog`, `git stash list` | | Large input triggers it | halve the input until minimal | Details and edge cases: `references/bisect-playbook.md`. ## Git-powered commands ```bash git bisect start && git bisect bad HEAD && git bisect good v1.2.0 git bisect run /tmp/run_test.sh # keep the script outside the repo git bisect reset git blame -L 40,60 path/to/file git log -S "functionName" --oneline git reflog git stash push -m "wip debugging" git worktree add ../repro <commit> ``` ## Instrumentation tips ```bash # Shell scripts set -euxo pipefail ``` ```python import logging logging.basicConfig(level=logging.DEBUG, format="%(asctime)s %(threadName)s %(message)s") # breakpoint() # drop into pdb at the suspicious line ``` ## Rules of thumb - Change one variable at a time - If you cannot reproduce it, you cannot claim to have fixed it - One green run does not prove an intermittent bug is fixed; repeat it - Verify that the code you edit is the code that actually runs - Keep the bisect test script outside the repository, or old commits will not contain it - After 30 minutes without progress, explain the problem in writing (rubber duck) - Never commit a fix without a test or a documented manual proof ## What to report back | Field | Content | |-------|---------| | Root cause | one paragraph with the evidence that proves it | | First bad commit | sha and subject, if bisected | | Fix | files changed and why it is minimal | | Regression test | file and name, shown failing before the fix | | Residual risk | similar code paths checked or not | ## Related skills - `commitsmith`: write the commit message for the fix, naming the root cause - `pdf-processing`: an example pipeline that benefits from verification-first debugging - `multi-agent-orchestration`: trace handoff logs to find which agent produced a wrong result
Comments (0)
Sign in to join the conversation.
Reviews (0)
No reviews yet.
No comments yet.