Debug

Debug

Debugging skill for LLM coding agents. Load this when the task is "fix the bug," "it's broken," "tests are failing," or any request that starts from a symptom rather than a feature.

Where [deliberate](../deliberate/SKILL.md) keeps code honest, this skill keeps diagnosis honest. Counters the failure mode of trying random fixes until symptoms go away.

---

1. Reproduce Before You Reason

No repro, no fix.

• Get the bug to happen on demand before touching code. A failing test is ideal; a manual repro with exact steps is the floor.
• If you can't reproduce, that's the first bug to fix. Don't guess at root cause from a log snippet.
• Write the repro down. It's the acceptance test for your fix.

If the user hands you a flaky or intermittent bug, say so:

> "I can trigger this maybe 1 in 5 times. Before fixing, I want to find conditions that make it reliable - otherwise I can't tell if a fix worked."

Test: Can I make this bug happen whenever I want?

---

2. Symptom, Cause, Fix - Keep Them Separate

The symptom is not the bug.

State all three out loud before editing:

• Symptom: what the user sees (error message, wrong output, crash).
• Cause: why it happens (the actual defect in logic, state, or assumption).
• Fix: the minimum change that addresses the cause.

If you can name the fix but not the cause, you're pattern-matching, not debugging. Stop.

Test: Could I explain to a new engineer why this bug existed, not just what I changed?

---

3. Bisect, Don't Guess

Narrow the search space systematically.

When the cause isn't obvious:

• Git bisect when a behavior regressed. It's faster than reading diffs.
• Binary search the code path: add a log or assertion halfway through, see which side the bug is on, repeat.
• Minimize the repro until only the bug-relevant code remains.
• Diff a working case against a broken case - the delta is the bug, almost always.

Random print statements across the codebase is not bisection. It's noise.

Test: Is each debugging step cutting the search space roughly in half?

---

4. Don't Mask - Understand

If the fix makes the symptom go away but you can't explain why, it's not a fix.

Common masking anti-patterns:

• Wrapping in try/catch to swallow an error you don't understand.
• Adding a null check without knowing why the value was null.
• Tweaking timeouts, retries, or sleeps to make flakiness "go away."
• Pinning a dependency to an old version without knowing what broke.

Every one of those is a future bug with a longer fuse. If you must ship a temporary mitigation, mark it explicitly:

> "This silences the error, but I don't yet know why x is null here. Filed as tech debt. Need to revisit before [trigger]."

Test: If someone asked me why this fix works, could I give a mechanism, not a vibe?

---

5. Suspect Your Assumptions First

The bug is usually where you're not looking.

The reason a bug is hard is that something you believe is true isn't. Enumerate the load-bearing assumptions:

• "This function is pure." - Is it really? Does it read a global, a clock, a random source?
• "This runs in order." - Is there async, a scheduler, a retry?
• "This input can't be null." - Says who? Check at the boundary.
• "The library behaves like the docs say." - Read the source or test it.

Then pick the assumption you'd be most embarrassed to be wrong about, and verify that one first.

Test: What am I assuming that I haven't verified?

---

6. Fix the Class, Not the Instance

Once you've found the cause, ask: where else does this pattern exist?

Most bugs aren't unique. A null-deref here often means the same unchecked input exists in three sibling call sites. A race condition in one handler often lives in every handler that shares the pattern.

• Grep for the pattern, not just the file.
• If the fix is a one-off patch, name why this site is special.
• If the fix is a rule ("always validate X at Y boundary"), apply the rule everywhere, or explain why you're not.

Don't silently expand scope - surface it:

> "The same pattern exists in three other places. I can fix this one site now and file the others, or fix all four. Which?"

Test: Is this a one-of-one bug, or a class of bugs I'm only patching once?

---

7. Write the Regression Test

A bug without a test is a bug that comes back.

• The repro from Section 1 becomes a test that fails before your fix and passes after.
• If the bug can't be tested at the unit level, test it at the integration level. Don't skip.
• If the bug is genuinely untestable (UI timing, hardware, external service), say so explicitly and log what you did to manually verify.

Landing a fix with no test is a decision, not a default. Own it.

Test: Would this exact bug be caught on the next commit if it reappeared?

---

These Guidelines Are Working If

• Fixes come with a named cause, not just a changed line.
• Debugging sessions get shorter over time because the first hypothesis is better.
• Regressions stop repeating because each bug leaves a test behind.
• "I don't know why it works" disappears from commit messages.

---

Part of Deliberate. Load alongside [deliberate](../deliberate/SKILL.md).

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: angad-kandhari
• Source: angad-kandhari/deliberate
• License: Apache-2.0

Install and usage instructions live in the source repository linked above.