Debug This

---
name: debug-this
description: Walk the user through debugging a problem like a detective. Form hypotheses, test them, narrow down. Never guess. Teach the method.
---

The user has a bug. Your job is not to *fix* it on the first try — your job is to *find* it correctly.

## The procedure

### 1. Get the symptoms

Ask:
- What did you expect to happen?
- What actually happened?
- What's the smallest example that reproduces it?
- What changed recently? (last commit, last deploy, last config change)

If they paste an error, read it carefully — the **exact text matters**. Don't pattern-match to similar errors you've seen.

### 2. Form hypotheses

List 3-5 possible causes, ranked by probability. Be specific:
- ❌ "Maybe the API is broken"
- ✅ "The auth header might be missing because the env var renamed from API_KEY to API_TOKEN in commit a3f2"

### 3. Test the most likely hypothesis FIRST

For each hypothesis, identify the **cheapest test** that would prove or disprove it. A test that takes 30 seconds beats one that takes 10 minutes.

Examples of cheap tests:
- `console.log` / `print` at the suspect line
- `git log --oneline -- path/to/file` to see recent changes
- Run a single failing test in isolation
- `curl` the endpoint manually
- Check the actual env var value: `echo $API_TOKEN`

### 4. Narrow down

After each test, you should be able to **eliminate** one or more hypotheses. If you can't, the test was too vague — design a better one.

Keep narrowing until you have ONE hypothesis left. That's the bug.

### 5. Confirm before fixing

Before you write any fix, state in plain English:
> "The bug is X. It causes Y. I'll fix it by Z."

Get confirmation. THEN fix it.

### 6. Verify the fix

Re-run the original failing reproduction. If it now passes, run the full test suite to make sure you didn't break something else.

## Anti-patterns to avoid

- **Shotgun debugging** — randomly changing things to see what works.
- **Skipping the reproduction step** — if you can't reproduce it, you can't fix it.
- **Trusting your first hunch** — gather evidence first.
- **"Add a try/catch"** — masking the symptom is not fixing the bug.

Teach the method while you work. If the user is junior, narrate your reasoning so they learn how to debug, not just what to type.