SKILL

---
name: debugger
description: Find the root cause of a bug. Hypothesis-first, evidence-driven. Don't patch the symptom; fix the cause and prove it.
category: review
version: 0.1.0
triggers: ["bug", "debug", "broken", "doesn't work", "failing test", "investigate", "why is X happening"]
applies_to: [openclaw, cursor, claude-code]
---

# Debugger

You investigate a bug or unexpected behaviour and find its **root cause** — not a place to
slap a try/except. You work hypothesis-first: state what you think is happening, prove or
disprove it with evidence, narrow down. The fix is the last step, not the first.

The most common AI failure here is jumping to a "fix" before understanding the cause,
which usually wraps the symptom and leaves the underlying bug. This skill exists to stop
that.

## When to use

- A test is failing and the cause isn't obvious from the failure message
- A user-reported bug that needs reproduction and root-cause analysis
- Unexpected behaviour ("the value should be X but is Y")
- Performance regression — finding what changed and why
- Race conditions, intermittent failures, "works on my machine" cases

Do not invoke for:
- Obvious typos / one-line bugs the user has already identified
- Feature requests dressed as bugs ("this should also do X")
- Code review (use `review/code-review`)

## Scope

In scope:
- Reproducing the bug
- Forming and testing hypotheses
- Narrowing the root cause
- Proposing a minimal correct fix
- Adding a regression test that would have caught it

Out of scope:
- Refactoring the surrounding area unless directly causal
- Performance work beyond fixing the regression
- Architectural changes — flag them as follow-ups, don't bundle

## Inherits

- [`meta/engineering-principles`](../../meta/engineering-principles/SKILL.md) — naming, no `any`, no silent try/except, modern standards as the rubric for the fix.
- [`meta/token-discipline`](../../meta/token-discipline/SKILL.md) — read the failure first, expand context only when evidence demands it.

## Token discipline (specific)

- **Start with the error.** Read the stack trace, the failing test output, the user's
  description in full. That's your evidence kernel — don't read the codebase yet.
- **Read the file at the top of the stack first.** Expand outward only when needed.
- **Grep for the symptom** before opening files. If the bug is "X is null", grep for where
  X is set, not where it's read.
- **Don't read tests of unrelated features.** Don't read history of unrelated commits.
- **Use `git log -p <file>` and `git blame`** when the bug is "this used to work" — usually
  cheaper than reading a 500-line file.

## Process

The debugger's discipline is **state your hypothesis, prove it, repeat**. Skipping steps
to "just try a fix" is how AI agents create new bugs.

1. **Understand the symptom.**
   - What does the user / test / error say? Quote it back in one sentence.
   - What's the expected behaviour vs. observed behaviour?
   - When did it start? (commit, deploy, version) — if unknown, ask.

2. **Reproduce.**
   - Get a deterministic reproduction. If you can't reproduce, you can't fix.
   - For intermittent bugs: identify the timing, ordering, or environmental trigger.
   - If reproduction needs data, document the minimal data set that triggers it.

3. **Form the first hypothesis.**
   - State what you think is happening, in one sentence.
   - Cite the lines of code that would produce that behaviour.
   - State what evidence would confirm or disprove it.

4. **Test the hypothesis.**
   - Read the cited code. Trace the data flow.
   - Run the relevant code path with logging or a debugger if available.
   - Write a tiny reproduction script if it speeds the loop.

5. **Iterate.** If hypothesis 1 was wrong, state hypothesis 2 with new evidence in mind.
   Each iteration narrows the scope. Don't loop on the same idea.

6. **Identify root cause.**
   - "X is null because Y wasn't set because Z runs before the init."
   - Distinguish *root cause* from *contributing factors*. The root cause is the change
     that, if reverted or fixed, makes the bug go away.

7. **Propose the minimal fix.**
   - Smallest change that addresses the root cause, not a workaround at the symptom.
   - If the minimal fix has wider implications, surface them — don't sneak them in.

8. **Add a regression test.** A test that fails before the fix and passes after. If the
   project doesn't have a test suite for this layer, surface that as a follow-up.

9. **Hand off.** Use `delivery/handoff` with the root cause, the fix, and what the
   regression test covers.

## Hypothesis log format

While investigating, keep a short hypothesis log. This forces clarity and prevents
repeated dead-ends.