debugging-systematic

Files (1)

• SKILL.md

SKILL.md (first lines)

# Systematic Debugging Methodology

## Core Principle

Debugging is not guessing. It is a scientific process: observe the symptom, form a hypothesis, predict the outcome of a test, and run the test. Repeat until the root cause is found.

---

## The Scientific Debugging Method

### Step 1: OBSERVE — Gather Evidence

Before changing anything, collect all available information.

**Checklist:**
- [ ] Read the FULL error message, not just the first line.
- [ ] Read the FULL stack trace. Identify the frame in YOUR code (skip framework internals).
- [ ] Note the exact input / request / action that triggered the bug.
- [ ] Note the expected behavior vs. the actual behavior.
- [ ] Check logs (application logs, server logs, browser console).
- [ ] Note the environment (OS, runtime version, dependency versions, config).
- [ ] Check if the bug is reproducible. If not, note the frequency and conditions.

**Key question:** Can I reproduce this bug reliably? If not, gathering more observations is the priority.

### Step 2: HYPOTHESIZE — Form a Theory

Based on the evidence, propose a specific, falsifiable explanation.

**Good hypothesis format:**
> "The crash occurs because `user.profile` is null when the user has not completed onboarding, and line 47 accesses `user.profile.name` without a null check."

**Bad hypothesis:**
> "Something is wrong with the user object."

**Rules:**
- The hypothesis must explain ALL observed symptoms.
- If it only explains some symptoms, it is incomplete — keep refining.
- Generate multiple competing hypotheses and rank by likelihood.

### Step 3: PREDICT — Design an Experiment

Before touching the code, predict what you will see IF your hypothesis is correct.

**Examples:**
- "If the null profile hypothesis is correct, then logging `user.profile` on line 45 will print `null` for users created after January 1."
- "If the race condition hypothesis is correct, then adding a 500ms delay before the second call will make the bug disappear."

### Step 4: TEST — Run the Experiment

Execute one change at a time. Observe whether the prediction matches.

**Rules:**
- Change ONE thing at a time. Multiple changes make it impossible to attribute cause.
- Revert experiments that did not help. Do not accumulate random changes.
- Use version control: commit or stash working state before experimenting.

### Step 5: CONCLUDE

- If the prediction matched, you have likely found the cause. Write a fix and a regression test.
- If the prediction did not match, your hypothesis was wrong. Return to Step 2 with new information.

---

## Binary Search Isolation

When you have no idea where the bug lives, use binary search to narrow it down.

### In Code
1. Identify the entry point and the crash / wrong output point.
2. Add a log or assertion at the MIDPOINT of the code path.
3. Is the state correct at the midpoint?
   - YES -> The bug is in the second half. Move your probe to the 75% point.
   - NO -> The bug is in the first half. Move your probe to the 25% point.
4. Repeat until you have isolated the exact line or function.

### In Time (git bisect)
```bash
git bisect start
git bisect bad              # Current commit is broken
git bisect good <commit>    # This commit was known to work
# Git checks out the midpoint. Test it.
git bisect good  # or  git bisect bad
# Repeat until git identifies the first bad commit.
git bisect reset
```

### In Data
1. Take the failing input dataset.
2. Remove half the data.
3. Does the bug still occur?
   - YES -> The bug is in the remaining half, or is independent of the removed data.
   - NO -> The trigger is in the removed half. Restore it and remove the other half.
4. Repeat until you find the minimum failing input.

---

## Reading Stack Traces

### Anatomy of a Stack Trace

```
Error: Cannot read properties of null (reading 'name')     <-- Error type + message
    at getUserName (src/services/user.js:47:22)             <-- YOUR CODE (start here)
    at handleRequest (src/routes/profile.js:12:15)          <-- Caller
    at Layer.handle (node_modules/express/lib/router.js:5)  <-- Framework (skip)
    at next (node_modules/express/lib/router.js:13)         <-- Framework (skip)
```

**Reading order:**
1. Read the error message at the top.
2. Scan DOWN the trace to find the FIRST frame in YOUR code.
3. Open that file at that line. This is your starting point.
4. Read the frames above and below for context on the call chain.

### Common Error Patterns

| Error Message | Likely Cause |
|---|---|

From Claude-Code-Community-Ireland/claude-code-resources, MIT.

More from Claude-Code-Community-Ireland/claude-code-resources