---
name: debug
description: Systematically diagnose and resolve a bug or unexpected behavior — reproduce, isolate, hypothesize, instrument, and verify. Use when the user reports a bug, says "this doesn't work", "why is this broken", or encounters unexpected behavior.
allowed-tools: Read, Grep, Glob, Bash
---

# Systematic Debugging

Read `learnings.md` beside this file before starting; append an entry when a bug's root cause defied a category below.

## Governing Principle

> **Bugs are information gaps.** Debugging is not guessing — it is a systematic process of narrowing the gap between expected and actual behavior until the root cause is isolated and verifiable.

## Procedure

1. **Reproduce** — confirm the bug exists and is deterministic. If the user hasn't described exact steps, ask. If it's intermittent, instrument logging before proceeding.

2. **Isolate** — narrow the scope:
   - **Discover** the entry point: which route, server function, or component is involved?
   - Trace the data flow from trigger to symptom. Read the code path, don't guess.
   - Identify the boundary where expected behavior diverges from actual behavior.

3. **Hypothesize** — form exactly ONE testable hypothesis. State it as: "The bug occurs because [X] causes [Y] at [file:line]." Never hold multiple hypotheses simultaneously — test one, discard or confirm, then move to the next.

4. **Instrument** — add the minimum observation needed to confirm or reject the hypothesis:
   - Console.log at the divergence point (remove after)
   - Read error output carefully — the first error in a stack is usually the root cause
   - Check types: is the runtime value what the type signature claims?
   - Check timing: is an async operation completing before it's consumed?

5. **Fix** — apply the narrowest possible change that addresses the root cause, not the symptom. **Constrain** the fix:
   - Does it match the project's established patterns? (`/patterns`)
   - Does it introduce a new failure mode?
   - Is the fix in the right layer? (data bug → fix in service, not in component rendering)

6. **Verify** — confirm the fix resolves the original reproduction AND doesn't break adjacent behavior:
   - Run the project's linter and type-checker
   - If tests exist, run them
   - Manually trace the fixed code path once more

## Common Bug Categories

| Category | First thing to check |
|---|---|
| **Type mismatch** | Runtime value vs declared type — look for `as any` casts hiding the real type |
| **Async race** | Missing `await`, check-then-act without atomicity (TOCTOU) |
| **State desync** | Cache not invalidated after mutation, stale closure in a hook |
| **Boundary violation** | Server code imported client-side, env variable missing at runtime |
| **Null path** | Optional field accessed without guard, empty array not handled |

## Constraints

- **Never guess-and-check.** Read the code path before changing anything.
- Remove all debugging instrumentation (console.log, temp vars) before considering the fix complete.
- If the bug reveals a missing pattern or architectural gap, flag it — don't silently patch around it.

## Handoffs

- Bug reveals a design problem → `/system-design`.
- Fix needs to follow an established pattern → `/patterns`.
- User wants to understand why the bug existed → `/teach`.
- Fix complete → `/full-review` to validate.