systematic-debugging · vstorm-co — Claude Code skill: what it does, how to install
systematic-debugging walks the agent through five debugging steps, from reproducing the failure to confirming the fix. Useful once random edits stop working.
MIT ★ 1,125 updated 2026-10-27
npx skills add vstorm-co/pydantic-deepagents --skill systematic-debugging -a claude-codeWhat systematic-debugging does
The skill pins the agent to a loop of five stages: reproduce, isolate, diagnose, fix, verify. Skipping ahead is ruled out, and so is repeated guess-and-check.
Most of the file is the small stuff that decides how long a bug lives. Which frame to read first in a stack trace, depending on the error type. Debug prints for C and for Python, plus a note to strip them once the bug is gone. Root causes worth ruling out early: an index off by one, signed versus unsigned mismatch, UTF-8 read as raw bytes, a relative path that breaks when the working directory changes.
Three failed attempts at the same fix mean the approach is wrong, not the details. The skill says to drop it and come at the problem from another angle. Nothing here runs your tests or attaches a debugger; SKILL.md is a set of instructions the agent follows while it works.
What it helps with
- Narrow a crash down to the smallest input that triggers it
- Read a stack trace and pick the frame to start from
- Tell a compile error apart from the cascade it causes
- Find why code finishes on small inputs and hangs on large ones
- Explain a test failure that never shows up locally
Example prompts for the agent
- Use the systematic-debugging skill: reproduce the failure in
pytest tests/test_parse.pybefore changing anything. - Walk the five steps on this segfault and tell me which stack frame to look at.
- That's the third failed patch. Switch strategy, as systematic-debugging says.
How to install systematic-debugging
1Skills CLI (Vercel)
npx skills add vstorm-co/pydantic-deepagents --skill systematic-debugging -a claude-code2Manually: put the files in place
~/.claude/skills/systematic-debugging/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/systematic-debugging/
1Skills CLI (Vercel)
npx skills add vstorm-co/pydantic-deepagents --skill systematic-debugging -a codex2Manually: put the files in place
.agents/skills/systematic-debugging/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add vstorm-co/pydantic-deepagents --skill systematic-debugging -a cursor2Manually: put the files in place
.cursor/skills/systematic-debugging/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install vstorm-co/pydantic-deepagents apps/cli/skills/systematic-debugging2Manually: put the files in place
.github/skills/systematic-debugging/SKILL.md1Skills CLI (Vercel)
npx skills add vstorm-co/pydantic-deepagents --skill systematic-debugging -a gemini-cli2Platform CLI
gemini skills install https://github.com/vstorm-co/pydantic-deepagents --path apps/cli/skills/systematic-debuggingManually: put the files in place
.devin/skills/systematic-debugging/SKILL.mdThe legacy .windsurf/skills/ path still works
Claude.ai
Zip the folder and upload it in Settings → Capabilities → Skills
Step by step, with commands for each platform: How to install skills in Claude Code: five ways
Questions about systematic-debugging
How do I install systematic-debugging in Claude Code?
Run npx skills add vstorm-co/pydantic-deepagents --skill systematic-debugging -a claude-code. The skill file lands at ~/.claude/skills/systematic-debugging/SKILL.md.
What does systematic-debugging do?
It keeps the agent on a five-step loop: reproduce, isolate, diagnose, fix, verify. Each step lists what to inspect and which debug prints to add.
What happens when a fix keeps failing?
After three unsuccessful tries with one approach, the skill tells the agent to abandon it and pick a different strategy rather than keep tweaking.
Source text
SKILL.md · MIT
---
name: systematic-debugging
description: "Systematic approach to diagnosing and fixing errors"
tags: [debugging, errors, benchmark]
version: "1.0.0"
---
# Systematic Debugging
A structured approach to finding and fixing bugs.
## The Debugging Loop
```
1. REPRODUCE → 2. ISOLATE → 3. DIAGNOSE → 4. FIX → 5. VERIFY
```
Never skip steps. Never guess-and-check repeatedly.
## Step 1: Reproduce
- Run the exact command that fails
- Capture FULL output (stdout AND stderr)
- Note: exit code, error message, stack trace
- If intermittent, identify what changes between runs
## Step 2: Isolate
- What's the MINIMAL input that triggers the error?
- Which specific line/function fails? (read the traceback bottom-up)
- Is it a compile error, runtime error, or wrong output?
- Does it fail on all inputs or specific ones?
## Step 3: Diagnose
### Read the error message carefully
| Error type | Where to look |
|-----------|---------------|
| Compile error | The FIRST error (later ones are often cascading) |
| Segfault | Last function in the stack trace, check array bounds and null pointers |
| Python traceback | The innermost frame (bottom), but also check the middle for context |
| Wrong output | Diff expected vs actual: `diff <(expected) <(actual)` |
| Timeout/hang | Is it an infinite loop? Deadlock? I/O bound? Add a timer or counter |
### Add minimal instrumentation
- C: `fprintf(stderr, "reached checkpoint %d\n", __LINE__);`
- Python: `print(f"DEBUG: {var=}", file=sys.stderr)`
- Check intermediate values, not just final output
- Remove debug prints after fixing
## Step 4: Fix
- Change ONE thing at a time
- If the same approach fails 3 times → completely different strategy
- Don't add workarounds — fix the root cause
- Common root causes:
- Off-by-one errors (loop bounds, array indexing)
- Type mismatches (int vs float, signed vs unsigned)
- Encoding issues (UTF-8 vs bytes)
- Path errors (relative vs absolute, missing trailing slash)
- Race conditions (file not written yet, process not started)
## Step 5: Verify
- Run the same command that failed before
- Test with multiple inputs, not just the one that was failing
- Check edge cases: empty input, single element, very large input
- Run any existing test suite
## Common Failure Patterns
### "It compiles but gives wrong output"
1. Print all intermediate values
2. Compare with a known-correct reference implementation
3. Check: integer overflow, floating point precision, endianness
### "It works on small input but times out on large"
1. Check algorithm complexity — O(n²) on 1M items = timeout
2. Profile: which loop/function takes the most time?
3. Restructure: hash maps, sorting, streaming
### "It works locally but fails in the test"
1. Check: absolute vs relative paths
2. Check: different working directory
3. Check: different input format than expected
4. Read the test script to understand what it actually checks
© vstorm-co · MIT · vstorm-co/pydantic-deepagents
Similar skills
All skills for Testing and QA →systematic-debugging by other authors comes first.