Systematic debugging
Skill charlieviettq/awesome-agent-skill/.claude/skills/systematic-debugging
Curated skill pack for LLM agents in engineer and science workflow (Cursor & Claude ready).
npx -y skills add charlieviettq/awesome-agent-skill --skill systematic-debuggingAssembled from the repository path, not quoted from the project. Check it against their README if it does not work.
One thing to look at
- 22 stars22 stars. Stars are a popularity signal and not a quality one, but at this level it is likely that nobody has read this closely except its author, and you would be relying on your own review.
What its author says it does
Copied from the file, not written here
Four-phase root-cause debugging—reproduce, compare patterns, hypothesize, fix with tests. Use when errors are unclear, fixes failed twice, or symptoms keep returning.
SKILL.md
2.1 KB, 450 tokens by cl100k_base, as published. Nobody here has run it
Systematic debugging
Iron law
No fixes without a reproduced failure and a testable hypothesis. After three failed fix attempts, question architecture or assumptions.
When to use
- Intermittent or unclear failures
- Prior "quick fixes" did not hold
- Multiple subsystems involved (API, DB, cache, agent tools)
When not to use
- Typo or one-line obvious fix with clear error message
- User only wants a stack trace explained, not a fix
Four phases
1. Reproduce
- Capture exact steps, inputs, environment, and error output
- Minimize repro (one test, one script, one URL)
- Confirm you can trigger the failure on demand
2. Compare
- What changed recently (code, config, deps, data)?
- Find a known-good comparison (last green commit, sibling module, docs example)
- Diff behavior, not only code
3. Hypothesize
- List 2–3 plausible causes ranked by likelihood
- For each: one experiment that would confirm or rule it out
- Prefer experiments that take minutes, not hours
4. Fix with test
- Add or extend a test that fails for the current bug
- Apply minimal fix; re-run repro and test
- Run
verify-before-donebefore claiming fixed
Escalation
| Signal | Action |
|---|---|
| 3+ failed fix attempts | Stop; write findings; propose design/architecture review |
| Cannot reproduce | Gather more data; do not patch blindly |
| Fix works locally only | Check env parity, feature flags, cached state |
Anti-patterns
- Random changes until something "seems" fixed
- Fixing symptoms (broad try/catch, silent rescue) without root cause
- Skipping repro because "it's obvious"
Related
test-first-development, test-failure-triage, verify-before-done, gstack/code-quality/investigate
Workflow inspired by obra/superpowers (MIT).
Gives 0 of the 12 instructions most debug triage skills give in 450 tokens
Counted across 839 of the 1,149 authors here whose files we hold, read 2026-08-06
- investigate root cause before proposing any fixin 102 of 839, across 65 files
- read error messages completelyin 90 of 839, across 48 files
- create a failing test case before fixingin 84 of 839, across 44 files
- reproduce the issue consistentlyin 82 of 839, across 40 files
- change one variable at a timein 82 of 839, across 42 files
- check recent changesin 74 of 839, across 35 files
- write the regression test before fixingin 74 of 839, across 36 files
- fix the root cause not the symptomin 60 of 839, across 43 files
- implement a single fix at a timein 59 of 839, across 20 files
- trace data flow backward to the sourcein 50 of 839, across 20 files
- remove all debug instrumentationin 49 of 839, across 13 files
- form a single hypothesisin 48 of 839, across 18 files
Said here and by no other author read
- minimize reproduction to one test or script
- confirm you can trigger the failure on demand
- diff behavior against a known-good comparison
- define one confirming experiment for each hypothesis
- prefer experiments that take minutes not hours
- add or extend a test that fails for the bug
Grouped from the skills themselves: near-identical wordings counted once, and counted by distinct author, so one author publishing three of these counts once. Length counted with cl100k_base; the agent that loads this file may tokenize it differently.