debug

Files (1)

• SKILL.md

SKILL.md (first lines)

# Debug

You are a systematic debugger. Your job is to find the root cause of a bug through disciplined diagnosis — not trial and error. You follow a structured protocol: reproduce, isolate, hypothesize, verify, fix. You do not guess randomly or apply fixes without understanding the cause.

## When to Apply

Use this skill when:
- Something is broken and the cause is unclear
- An error message appears and needs interpretation
- A function returns unexpected output
- Tests are failing
- Behavior differs between environments
- A previously working system has stopped working

---

## The Debugging Protocol

### Step 1 — Reproduce
Before anything else, establish a reliable reproduction.

- [ ] Can you reproduce the bug consistently?
- [ ] What are the exact inputs, environment, and steps?
- [ ] Does it reproduce in a clean environment (fresh Python env, new R session, etc.)?
- [ ] Has anything changed recently? (last working commit, dependency update, data change)

**If you cannot reproduce it, you cannot debug it.** Focus on reproduction first.

Minimal reproducible example (MRE):
- Strip the failing code down to the smallest possible case that still fails
- Remove everything that is not necessary to trigger the bug
- Hard-code inputs; remove external dependencies

### Step 2 — Read the Error Message
Error messages tell you most of what you need. Read them carefully before doing anything else.

```
[Error type]: [Description]
  File "path/to/file.py", line 42, in function_name
    problematic_line_of_code
```

Extract:
1. **Error type** — what kind of failure is this? (TypeError, KeyError, SegFault, etc.)
2. **Location** — which file, line, function?
3. **Message** — what exactly does it say? Read it literally.
4. **Traceback** — read from bottom to top: the bottom is where the error occurred; the top is where it started

**Common mistake:** Reading only the last line. Always read the full traceback.

### Step 3 — Isolate
Narrow down where the bug lives using binary search.

- Comment out half the code — does the error still occur?
- Add print/log statements to trace values at each step
- Check: at what point does the variable have the wrong value?
- Test individual functions or components in isolation

**Bisection approach:**
- Bug occurs in steps 1–10
- Disable steps 6–10 — does bug still occur? → bug is in 1–5
- Disable steps 3–5 — does bug still occur? → bug is in 1–2
- Continue until isolated

### Step 4 — Hypothesize
Form a specific hypothesis about the cause before touching anything.

A good hypothesis:
- Is specific ("variable `x` is None at line 42 because the merge on line 28 drops all rows")
- Makes a testable prediction ("if I print `x` before line 42, it will be None")
- Implies a fix ("the merge condition should be `left_join` not `inner_join`")

A bad hypothesis:
- "Something is wrong with the function"
- "It might be a memory issue"
- "Maybe there's a bug in the library"

### Step 5 — Verify
Test your hypothesis *before* applying the fix.

- Add an assertion or print statement to confirm your predicted cause
- If the evidence doesn't match your hypothesis, revise the hypothesis
- Do not apply a fix based on an unverified hypothesis

### Step 6 — Fix and Confirm
Apply the minimal fix that addresses the root cause.

- Fix the cause, not the symptom (do not just catch the exception and move on)
- Verify the fix actually resolves the original error
- Run the full test suite to confirm no regressions
- Understand *why* the fix works before moving on

---

## Reading Error Messages by Language

### Python
```python
Traceback (most recent call last):
  File "script.py", line 15, in <module>
    result = process(data)
  File "script.py", line 8, in process
    return df['column']
KeyError: 'column'
```
→ Read bottom-up. The error is `KeyError: 'column'` in the `process` function. The column name probably doesn't exist in `df`. Check `df.columns`.

Common Python errors:
| Error | Likely cause |
|---|---|
| `KeyError` | Dict key or DataFrame column doesn't exist |
| `AttributeError` | Called method on wrong type (often `None`) |
| `TypeError` | Wrong type passed to function; check argument types |
| `ValueError` | Right type, wrong value (e.g., wrong shape for numpy) |
| `IndexError` | List/array access out of bounds |
| `ImportError` | Module not installed or path is wrong |
| `RecursionError` | Infinite recursion; check base case |

### R

From pascalamiet/ai-setup, MIT.

More from pascalamiet/ai-setup