systematic-debugging

Files (3)

• SKILL.md
• external-research-guide.md · references/
• root-cause-tracing.md · references/

SKILL.md (first lines)

# Systematic Debugging

## Overview

Guessing fixes wastes time and creates new bugs. Quick patches hide root problems.

**Core principle: Never fix before finding the root cause. Symptom fixing is failure.**

## Iron Law

```
Never propose a fix without root cause investigation.
```

Phase 0 or Phase 1 must be completed before any fix is proposed.
Phase 0 fixes are ONLY allowed when ALL of these are true:
- External research found an official solution or known issue for this exact error
- Change is single file, single point (config value, import, typo)
- No logic changes

## When to Use

**All technical problems:**
- Test failures, build errors, deploy errors
- Config conflicts, dependency issues
- Infrastructure/environment problems
- Unexpected behavior, performance issues

**Especially when:**
- Under time pressure (urgency breeds guessing)
- "Let me just quickly fix this" comes to mind
- Multiple fix attempts have already been tried
- Previous fixes didn't work
- You don't fully understand the problem

## The Phases

Each Phase must complete before proceeding to the next.

### Phase 0: Quick Assessment

Run immediately when an error occurs. Before any fix attempt.

1. **Classify the error** — read the error message/symptoms:
   - Same code works in different environment? → Environment issue
   - After recent dependency/version change? → Dependency issue
   - Only fails in specific code path? → Code issue

2. **External research (exact match, 5 min max)** — check official docs and GitHub Issues for known issues. Don't rely on self-knowledge alone.
   - See: `references/external-research-guide.md`

3. **Branch decision**:
   - All Iron Law conditions met → Fix in Phase 0
   - Any condition unmet → Enter Phase 1 full process
   - **Phase 0 quick-fix fails**: Undo (git checkout/undo), enter Phase 1. This attempt counts in the fix counter.

### Phase 1: Root Cause Investigation

**Before any fix attempt:**

1. **Read the error carefully**
   - Don't skip errors/warnings
   - Read the entire stack trace
   - Record line numbers, file paths, error codes

2. **Reproduce consistently**
   - Get exact reproduction steps
   - Every time? If intermittent, collect more data

3. **Check recent changes**
   - git diff, recent commits
   - New dependencies, config changes
   - Environment differences (env vars, Node/runtime version, OS)

4. **Research external sources (deep read)**
   - Based on Phase 0 exact match results, investigate further
   - Read official docs for the failure mechanism
   - Check release notes for breaking changes
   - See: `references/external-research-guide.md`

5. **Collect evidence in multi-component systems**
   - Log data in/out at each component boundary
   - Run once to find where it breaks
   - Then deep-dive into that component

6. **Trace data flow**
   - Where does the wrong value originate?
   - Trace the call stack backwards to the source
   - See: `references/root-cause-tracing.md`

### Phase 2: Pattern Analysis

1. **Find similar working code** in the same codebase
2. **Compare with reference implementations** — read the full reference docs, don't skim
3. **Identify all differences** between working and broken — don't assume "that's irrelevant"
4. **Map dependencies** — what config, environment, other components are needed

### Phase 3: Hypothesis and Testing

**Before entering Phase 3:**
- Verify clean state (git status)
- If not clean: git stash or save checkpoint
- On hypothesis failure: rollback to safe point, try new hypothesis (no cumulative fixes)

1. **Form a single hypothesis**: "X is the root cause because Y" — specific, not vague
2. **Test minimally**: smallest change to verify the hypothesis. One variable at a time.
3. **Verify before proceeding**:
   - Success → Phase 4
   - Failure → **New hypothesis** (don't stack fixes on top of failed ones)

### Phase 4: Implementation

1. **Write a failing test** — simplest reproduction, automated if possible, before fixing
2. **Apply a single fix** — only the identified root cause, one change at a time, no "while I'm at it"
3. **Verify the fix** — test passes? No other tests broken? Problem actually resolved?
4. **If fix doesn't work**:
   - How many fix attempts so far?
   - Under 3: return to Phase 1 with new information
   - **3 or more: proceed to Phase 4.5**

From sangrokjung/claude-forge, MIT.

More from sangrokjung/claude-forge