Skip to main content
skill CX Codex

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

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add vstorm-co/pydantic-deepagents --skill systematic-debugging -a claude-code
Open on GitHub

What 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.py before 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-code

2Manually: put the files in place

~/.claude/skills/systematic-debugging/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/systematic-debugging/

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.

systematic-debugging Jesse Vincent systematic-debugging is a Claude Code and Codex skill that blocks fixes until root cause analysis is complete. It activates on test failures, bugs, or unexpected behavior. CX Codex +1 306,118installs systematic-debugging spencerpauly systematic-debugging enforces a structured debugging workflow on your AI assistant instead of random edits. It helps isolate elusive bugs and verify root causes with evidence. CX Codex +1 604installs systematic-debugging bobmatnyc The systematic-debugging skill guides an agent from reproducing a bug to checking the fix. Use it when an error or unexpected behavior has no clear cause. CX Codex +1 400installs systematic-debugging ChrisWiles systematic-debugging enforces a four-phase troubleshooting protocol rooted in root cause analysis. Ideal for tracking down broken test suites or runtime errors without trial-and-error edits. CX Codex +1 ★ 6,091repo stars systematic-debugging GanyuanRan The systematic-debugging skill guides bug and test-failure investigations before code changes. Use it to trace a symptom to the logic that owns the cause. CX Codex +1 ★ 1,450repo stars debugging-toolkit-debugger Seth Hobson The debugging-toolkit-debugger subagent investigates errors, failed tests, and odd behavior by tracing failures to their cause and checking a focused fix. CX Codex ★ 42,780repo stars gaia-debugging ruvnet gaia-debugging diagnoses why a GAIA benchmark task failed: extracts the trace, classifies the failure mode, and proposes a fix. Runs when gaia-bench run reports failed or incorrect answer for a task_id. CX Codex +1 436installs n8n-debugging-official n8n-io n8n-debugging-official diagnoses failing n8n workflows, execution errors, and unexpected node output. It helps pinpoint why an execution halted or why expressions return null. CX Codex +1 2,600installs debugging-mwaa-workflow aws debugging-mwaa-workflow diagnoses Amazon MWAA workflow failures (Provisioned and Serverless). Reads CloudWatch logs, calls REST API via aws mwaa invoke-rest-api, gathers context, and gives remediation commands. CX Codex +1 1,700installs debug-systematic travisjneuman debug-systematic — a four-phase debugging skill for hard-to-reproduce failures, race conditions, and unexplained behavior. It guides the agent from reproduction to verified fix. CX Codex +1 152installs laravel-systematic-debugging iSerter The laravel-systematic-debugging skill guides an agent through investigating Laravel errors before changing code. Use it for failing tests, Eloquent issues, and unexpected application behavior. CX Codex +1 110installs

From the same set14

The whole set →
environment-discovery The environment-discovery skill trains Claude Code to systematically explore unfamiliar environments before making changes. It checks file structure, data formats, available tools, and existing code—saving debugging time. CX Codex +1 ★ 1,125repo stars report-writing report-writing provides guidelines for structuring analytical reports, drafting stand-alone executive summaries, and citing sources. CX Codex +1 ★ 1,125repo stars build-and-compile The build-and-compile skill helps Claude Code choose build commands from a project's files and troubleshoot compiler or dependency errors. Use it when a build fails or the project setup is unclear. CX Codex +1 ★ 1,125repo stars research-methodology research-methodology — a skill with methodology for structured research: three-phase search, source reliability ranking, and note-taking with confidence levels for each finding. CX Codex +1 ★ 1,125repo stars performant-code performant-code guides Claude Code to write fast routines for large files and strict memory caps. Helps prevent runtime timeouts on heavy workloads. CX Codex +1 ★ 1,125repo stars data-formats The data-formats skill guides file inspection before parsing, from checking binary signatures to sampling large structured files. Use it when a file’s format is unclear. CX Codex +1 ★ 1,125repo stars verification-strategy verification-strategy — a structured checklist skill for Claude Code to audit file outputs, compiler flags, exit codes, and edge cases before declaring a task finished. CX Codex +1 ★ 1,125repo stars diagram-design The diagram-design skill guides research diagram creation on an Excalidraw canvas through MCP. Use it to map comparisons, processes, architectures, or timelines. CX Codex +1 ★ 1,125repo stars

Project sponsors

Companies that keep this analytics open