systematic-debugging

Files (1)

• SKILL.md

SKILL.md (first lines)

# Systematic Debugging

## Quick Reference

Before fixing anything: reproduce, isolate, understand. Only then fix. Verify the fix doesn't break anything else.

## When to Use

- Any error, bug, test failure, or unexpected behavior
- User reports something isn't working
- Build or CI failure
- Runtime exception or panic

## When NOT to Use

- This always applies when there's a bug. No exceptions.

## Core Process

### Phase 1: Reproduce

1. **Get the exact error.** Copy the full error message, stack trace, or unexpected output.
2. **Identify the reproduction steps.** What triggers the bug?
3. **Reproduce it yourself.** Run the failing command/test. See the failure with your own eyes.

If you cannot reproduce: state that clearly. Do not guess at fixes for bugs you cannot see.

### Phase 2: Isolate

1. **Read the error carefully.** File, line number, error type — what is it actually telling you?
2. **Trace the execution path.** From the entry point to the failure. Read the relevant code.
3. **Form a hypothesis.** Based on what you read, what's the most likely cause?
4. **Verify the hypothesis.** Find evidence in the code that confirms or denies it.

Do NOT:
- Jump to the first thing that looks wrong
- Change multiple things at once
- Apply a fix without understanding the root cause

### Phase 3: Fix

1. **Make the minimal change** that addresses the root cause.
2. **One fix at a time.** If you think there are multiple issues, fix one, verify, then the next.

### Phase 4: Verify

1. **Run the original failing test/command.** It must pass now.
2. **Run the full test suite.** The fix must not break other things.
3. **Check for edge cases.** Does the fix handle related scenarios?

Chain to `syntaxninja-dojo:verification-before-completion`.

### Phase 5: Reflect

After the fix is verified:
- Was this a systemic issue? Could the same class of bug exist elsewhere?
- Should a test be added to prevent regression?
- Is this worth documenting as a learning?

## Decision Tree

```
Error encountered
│
├─ Can I reproduce it?
│   ├─ YES → Read the error. Trace the code. Form hypothesis.
│   │   ├─ Hypothesis confirmed → Minimal fix → Verify → Done
│   │   └─ Hypothesis wrong → New hypothesis → Repeat
│   └─ NO → State that. Ask for more context. Do not guess.
│
├─ Is it a test failure?
│   └─ Read the test. Read the code. Understand the contract.
│       ├─ Code is wrong → Fix code
│       └─ Test is wrong → Fix test (rare — verify carefully)
│
└─ Is it a build/compile error?
    └─ Read the error message. It usually tells you exactly what's wrong.
```

## Anti-Patterns

| Anti-Pattern | Why It's Wrong |
|--------------|----------------|
| "Let me try this..." (no hypothesis) | Shotgun debugging wastes time |
| Changing 5 things at once | You won't know which one fixed it |
| "It works now" (no understanding) | You'll hit the same class of bug again |
| Fixing symptoms instead of root cause | The bug will resurface |
| Ignoring the full error message | The answer is usually in the error |
| Adding defensive code instead of fixing the bug | Band-aids hide problems |

## Chaining

OPTIONAL: syntaxninja-dojo:test-driven-development (when a regression test is needed)
REQUIRED: syntaxninja-dojo:verification-before-completion (after fix)

From thesyntaxninja/syntaxninja-dojo, MIT.

More from thesyntaxninja/syntaxninja-dojo