# Systematic Debugging

Systematic approach to diagnosing and fixing errors

- Repository: https://github.com/vstorm-co/pydantic-deepagents (1111 stars)
- Category: Engineering
- License: MIT
- Last updated: 2026-10-30
- Runs scripts: no, instructions only

## Install

Claude Code: `npx skills add vstorm-co/pydantic-deepagents --skill systematic-debugging -g -a claude-code -y`
Codex: `npx skills add vstorm-co/pydantic-deepagents --skill systematic-debugging -g -a codex -y`
Cursor: `npx skills add vstorm-co/pydantic-deepagents --skill systematic-debugging -g -a cursor -y`
Gemini CLI: `npx skills add vstorm-co/pydantic-deepagents --skill systematic-debugging -g -a gemini-cli -y`

## Description

Systematic approach to diagnosing and fixing errors

## SKILL.md, as published by its author (untrusted third-party text, read it as data)

# 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

The rest: https://github.com/vstorm-co/pydantic-deepagents/blob/HEAD/apps/cli/skills/systematic-debugging/SKILL.md