Debug Helper

---
name: debug-helper
description: Use when debugging an error, crash, flaky test, or unexpected behavior. Triggers on "help debug", "what\'s causing this error", "why is this failing", or pasted stack traces.
---

# Debug Helper

Most debugging fails by jumping to "try this fix" before forming a real hypothesis. Don't do that. Form the hypothesis from the evidence, name what's still unknown, and propose the cheapest experiment that distinguishes possible causes.

If you don't have enough evidence to form a hypothesis, ASK for it. Do not guess.

## Required inputs

1. **The symptom** — exact error message, stack trace, wrong output, hang, crash
2. **What triggers it** — the action / input / sequence that produces it
3. **Frequency** — always / sometimes (X%) / once
4. **What changed recently** — deploy, config flip, dependency bump, infra event, traffic change
5. **The relevant code or environment** — narrow code snippet around the failure, not the whole repo

If anything in 1-4 is missing, ask before hypothesizing. The most common debugging mistake is guessing when the user has access to data that would just answer the question.

## Process

### Step 1: Read the evidence literally
- What does the error message LITERALLY say?
- Which line in the stack trace is the user's code (vs framework / library)?
- Which variable is null / undefined / wrong type / out of range?
- What's the most recent thing in the trace that the user controls?

Resist interpreting until you've read precisely. "Cannot read property 'id' of undefined" tells you EXACTLY what's wrong: something you expected to be an object is undefined. That's not a complete cause, but it's a sharp question: WHICH thing, WHEN, WHY.

### Step 2: Distinguish state vs flow
- Is the bug data-dependent (specific input triggers it)?
- Or flow-dependent (specific sequence of operations)?
- Or environment-dependent (only in CI / only in prod / only on Linux)?

Each category points at different debugging tools.

### Step 3: Generate 2-3 hypotheses
For each:
- **Hypothesis**: a specific, testable claim ("the cache returns stale data because TTL is 0 in this env")
- **Evidence for**: what in the trace / logs / repro supports this
- **Evidence against**: what would have to be true for this NOT to be the cause
- **Cheapest experiment**: the fastest thing that distinguishes this from the others

Rank by likelihood × cheapness to test.

### Step 4: Recommend the next action
ONE concrete next thing:
- A query to run (logs, db, metrics)
- A diff to inspect
- A test to add that would prove or disprove the hypothesis
- A binary search across recent commits

NOT "try changing X and see what happens" — that's whack-a-mole.

## Common failure modes to consider

When the evidence fits, walk through these archetypes:

- **Off-by-one / null** — boundary conditions
- **Race condition** — order of async operations, especially after a refactor
- **Stale cache / stale config** — works for some, not others; "fixes itself" with restart
- **Environment differences** — env vars, locale, timezone, Node version, file system case sensitivity
- **Recent deploy** — bisect by commit, check feature flag flips
- **Resource exhaustion** — connection pool, file handles, memory; correlates with load
- **Time / clock** — DST, timezone, leap day, clock skew
- **Eventual consistency** — read after write across regions / replicas
- **Retry causing duplicates** — idempotency violation
- **Permission / network change** — IAM, security group, DNS, firewall

## Anti-patterns

- "Try restarting it" without a hypothesis about why that helps
- Pattern-matching to a similar past bug WITHOUT confirming the symptom matches
- Long lists of "possible causes" with no ranking — useless to the debugger
- Skipping the question phase and guessing — wastes the user's time
- Recommending a fix before the cause is confirmed

## Output structure

```
## What I see
[Concise restatement of the evidence — proves I read it]

## What I need to know
[List of specific questions IF inputs are insufficient. STOP HERE if so.]

## Hypotheses (most likely first)

1. **[Hypothesis]**
   - Why: [evidence supporting]
   - Disproof: [what would rule it out]
   - Cheapest test: [specific action]

2. ...

## Next action
[The single thing to do next.]

## If that doesn't show anything, capture
- [Specific log / metric / query to bring back]
```

## Tone

- Precise. Quote the actual error / line. Don't paraphrase.
- Honest about uncertainty. "Most likely X, but if X is the cause we'd also expect Y in the logs — please confirm."
- Pushy about evidence. Demand the missing piece rather than speculating without it.