# Systematic Debugging

> Use when encountering any bug, test failure, or unexpected behavior, before proposing fixes

- Skill: `wukongnotnull/systematic-debugging` (Agent Skill, multi-file: 12 files)
- Install (CLI): `npx skillmds@latest add wukongnotnull/systematic-debugging`
- Raw SKILL.md: https://api.skillmd.com/api/skills/wukongnotnull/systematic-debugging/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: wukongnotnull (https://skillmd.com/u/wukongnotnull)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/wukongnotnull/systematic-debugging

---


# Systematic Debugging

## Overview

Random fixes waste time and create new bugs. Quick patches mask underlying issues.

**Core principle:** ALWAYS find root cause before attempting fixes. Symptom fixes are failure.

**Violating the letter of this process is violating the spirit of debugging.**

## The Iron Law

```
NO FIXES WITHOUT ROOT CAUSE INVESTIGATION FIRST
```

If you haven't completed Phase 1, you cannot propose fixes.

## When to Use

Use for ANY technical issue:
- Test failures
- Bugs in production
- Unexpected behavior
- Performance problems
- Build failures
- Integration issues

**Use this ESPECIALLY when:**
- Under time pressure (emergencies make guessing tempting)
- "Just one quick fix" seems obvious
- You've already tried multiple fixes
- Previous fix didn't work
- You don't fully understand the issue

**Don't skip when:**
- Issue seems simple (simple bugs have root causes too)
- You're in a hurry (rushing guarantees rework)
- Manager wants it fixed NOW (systematic is faster than thrashing)

## Focused path

Use this shorter path when **all** are true:

- A single failing test or assertion is identified (e.g. from CI logs)
- You can reproduce it locally and stably
- The change surface is clear (e.g. files touched in the failing change)

**Focused steps:**

1. Read the failure and relevant diff/context (understand WHAT failed and WHY at the failing locus)
2. Create or tighten a regression test (`wukong-code:test-driven-development`)
3. Implement the fix at the root cause for that failure—no bundled unrelated changes
4. Run focused checks, then the broader suite needed for the claim

The Iron Law still holds: no fix before you understand the failing cause. Focused path skips the full multi-phase *narration*, not investigation.

**Use the full Four Phases instead when:**

- The failure crosses service/process boundaries
- Root cause is unclear after one focused attempt
- Reproduction is inconsistent

## The Four Phases

When Focused path does not apply, you MUST complete each phase before proceeding to the next.

### Phase 1: Root Cause Investigation

**BEFORE attempting ANY fix:**

1. Read error messages carefully (stack traces, line numbers, error codes)
2. Reproduce consistently (exact steps; if not reproducible, gather more data)
3. Check recent changes (git diff, commits, dependencies, config, environment)
4. Gather evidence at component boundaries in multi-component systems
5. Trace data flow to source (see `root-cause-tracing.md`)

### Phase 2: Pattern Analysis

1. Find working examples similar to what's broken
2. Compare against references — read completely, don't skim
3. Identify every difference between working and broken
4. Understand dependencies, config, environment, assumptions

### Phase 3: Hypothesis and Testing

1. Form single hypothesis: "I think X because Y"
2. Test minimally — one variable at a time
3. Verify before continuing; if failed, form NEW hypothesis
4. When you don't know — say so, ask for help, research more

### Phase 4: Implementation

1. Create failing test case (use `wukong-code:test-driven-development`)
2. Implement single fix at root cause — no bundled changes
3. Verify fix (test passes, no regressions, issue resolved)
4. If fix doesn't work: STOP. Return to Phase 1, or if ≥3 fixes failed, question architecture with your human partner

For full phase detail, multi-component instrumentation examples, and architecture-questioning guidance, Read `skills/systematic-debugging/references/rationalizations-and-depth.md`

## Red Flags - STOP and Follow Process

If you catch yourself thinking:
- "Quick fix for now, investigate later"
- "Just try changing X and see if it works"
- "Add multiple changes, run tests"
- "Skip the test, I'll manually verify"
- "It's probably X, let me fix that"
- "I don't fully understand but this might work"
- "Pattern says X but I'll adapt it differently"
- "Here are the main problems: [lists fixes without investigation]"
- Proposing solutions before tracing data flow
- **"One more fix attempt" (when already tried 2+)**
- **Each fix reveals new problem in different place**

**ALL of these mean: STOP. Return to Phase 1.**

**If 3+ fixes failed:** Question the architecture (see `skills/systematic-debugging/references/rationalizations-and-depth.md`, Phase 4.5 / architecture questioning section)

## your human partner's Signals You're Doing It Wrong

**Watch for these redirections:**
- "Is that not happening?" - You assumed without verifying
- "Will it show us...?" - You should have added evidence gathering
- "Stop guessing" - You're proposing fixes without understanding
- "Ultra-think this" - Question fundamentals, not just symptoms
- "We're stuck?" (frustrated) - Your approach isn't working

**When you see these:** STOP. Return to Phase 1.

## Quick Reference

| Path / Phase | Key Activities | Success Criteria |
|--------------|----------------|------------------|
| **Focused** | Single fail + stable repro + clear surface → regress test → fix → focused + needed suite | Bug resolved without full phase narration |
| **1. Root Cause** | Read errors, reproduce, check changes, gather evidence | Understand WHAT and WHY |
| **2. Pattern** | Find working examples, compare | Identify differences |
| **3. Hypothesis** | Form theory, test minimally | Confirmed or new hypothesis |
| **4. Implementation** | Create test, fix, verify | Bug resolved, tests pass |

## When Process Reveals "No Root Cause"

If systematic investigation reveals issue is truly environmental, timing-dependent, or external:

1. You've completed the process
2. Document what you investigated
3. Implement appropriate handling (retry, timeout, error message)
4. Add monitoring/logging for future investigation

**But:** 95% of "no root cause" cases are incomplete investigation.

## Supporting Techniques

These techniques are part of systematic debugging and available in this directory:

- **`root-cause-tracing.md`** - Trace bugs backward through call stack to find original trigger
- **`defense-in-depth.md`** - Add validation at multiple layers after finding root cause
- **`condition-based-waiting.md`** - Replace arbitrary timeouts with condition polling

**Related skills:**
- **wukong-code:test-driven-development** - For creating failing test case (Phase 4, Step 1)
- **wukong-code:verification-before-completion** - Verify fix worked before claiming success

For rationalizations, phase depth, and real-world impact data, Read `skills/systematic-debugging/references/rationalizations-and-depth.md`