systematic-debugging

Files (1)

• SKILL.md

SKILL.md (first lines)

# Systematic Debugging — Mandatory Skill

**Agent:** Analyst (Phase 1: Investigation), Builder (Phase 2: Fix)
**Phase:** DEBUG workflow — all phases
**Priority:** CRITICAL — This skill is NON-NEGOTIABLE during DEBUG workflow

---

## IRON LAW

**NO FIXES WITHOUT ROOT CAUSE INVESTIGATION FIRST.**

Do not guess. Do not "try something." Do not apply the first fix that comes to mind.
Investigate. Understand. Then fix.

---

## The 4-Phase Debugging Process

```mermaid
graph TD
    A[Bug Report / Symptom] --> B[Phase 1: Root Cause Analysis]
    B --> C{Root cause identified?}
    C -->|No| D[Gather more evidence]
    D --> B
    C -->|Yes| E[Phase 2: Pattern Analysis]
    E --> F{Seen this pattern before?}
    F -->|Yes| G[Check memory for previous fix]
    F -->|No| H[Document as new pattern]
    G --> I[Phase 3: Hypothesis & Testing]
    H --> I
    I --> J{Fix attempt #?}
    J -->|1-3| K[Implement minimal fix]
    K --> L[Write failing test FIRST]
    L --> M[Apply fix]
    M --> N{Tests pass?}
    N -->|No| J
    N -->|Yes| O[Phase 4: Verification]
    O --> P[Run full test suite]
    P --> Q{All pass?}
    Q -->|No| R[Fix broke something else.<br/>Revert. Return to Phase 1.]
    Q -->|Yes| S[Done: Document in result.md]
    J -->|4+| T[STOP: 3-Fix Escalation.<br/>Write escalation.md.<br/>Present to user.]
```

---

## Phase 1: Root Cause Analysis

**Objective:** Understand WHY the bug exists, not just WHAT it does.

### Mandatory Steps

1. **Reproduce the bug.** If you can't reproduce it, you don't understand it.
   - Write exact steps to trigger the bug.
   - Note environment details (browser, OS, Node version, config).
   - Confirm reproduction is consistent (try 3 times).

2. **Gather evidence.** Do NOT hypothesize until you have data.
   - Read error messages and stack traces verbatim.
   - Check logs for the time window around the failure.
   - Run `git log --since="2 days ago" --oneline` to find recent changes.
   - Check memory/patterns.md for similar past issues.

3. **Trace the data flow backward.**
   - Start at the failure point (the error/wrong output).
   - Walk backward through the code: what function called this? What data did it pass?
   - At each step, verify the data is what you expect.
   - The first place where data diverges from expectation is likely the root cause.

4. **Identify the root cause.**
   - The root cause is the EARLIEST point in the chain where behavior diverges from specification.
   - "The button doesn't work" is a symptom. "The event handler references a stale closure" is a root cause.

### Phase 1 Gate
Before proceeding to Phase 2, you MUST have:
- [ ] Reproduction steps (tested and consistent)
- [ ] Evidence collected (logs, errors, stack traces)
- [ ] Root cause identified (specific code location and mechanism)
- [ ] Root cause explains ALL symptoms (not just some)

---

## Phase 2: Pattern Analysis

**Objective:** Determine if this bug is an instance of a known pattern.

### Steps

1. **Check memory.** Read `.opencode/context/01_memory/patterns.md`:
   - Has this exact bug occurred before?
   - Has a similar class of bug occurred? (e.g., "stale closure" bugs)
   - What was the previous fix? Did it work?

2. **Classify the bug type:**
   - **Logic error:** Wrong algorithm, wrong condition, off-by-one
   - **State management:** Stale state, race condition, missing update
   - **Integration:** API contract mismatch, data format mismatch
   - **Environment:** Config, dependency version, platform difference
   - **Regression:** Worked before, broken by recent change

3. **Document the pattern** for future reference.

### Phase 2 Gate
Before proceeding to Phase 3, you MUST have:
- [ ] Memory checked for similar past issues
- [ ] Bug classified by type
- [ ] If recurring pattern: previous fix reviewed for effectiveness

---

## Phase 3: Hypothesis & Testing

**Objective:** Fix the bug using the scientific method — one variable at a time.

### The Scientific Method for Debugging

1. **State your hypothesis clearly:**
   > "The bug occurs because [specific mechanism]. Fixing [specific thing] should resolve it because [reasoning]."

From lshtram/nso, MIT.

More from lshtram/nso