Systematic debugging
Skill charlieviettq/awesome-agent-skill/.cursor/skills/core-workflow/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. Triggers: "root cause", "debug systematically", "why is this broken", "still failing".
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).