# Debug > Debugging discipline. Load when the task is fixing a bug, triaging a symptom, or chasing a failing test. Covers reproducing before reasoning, separating symptom from cause, bisecting systematically, not masking what you don't understand, suspecting assumptions, fixing the class not the instance, and leaving a regression test. - **Type:** Skill - **Install:** `agentstack add skill-angad-kandhari-deliberate-debug` - **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior - **Seller:** [angad-kandhari](https://agentstack.voostack.com/s/angad-kandhari) - **Installs:** 0 - **Category:** [AI & ML](https://agentstack.voostack.com/c/ai-and-ml) - **Latest version:** 0.1.0 - **License:** Apache-2.0 - **Upstream author:** [angad-kandhari](https://github.com/angad-kandhari) - **Source:** https://github.com/angad-kandhari/deliberate/tree/main/skills/debug ## Install ```sh agentstack add skill-angad-kandhari-deliberate-debug ``` Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent. ## About # 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](https://github.com/angad-kandhari/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](https://github.com/angad-kandhari) - **Source:** [angad-kandhari/deliberate](https://github.com/angad-kandhari/deliberate) - **License:** Apache-2.0 Install and usage instructions live in the source repository linked above. ## Pricing - **Free** — Free ## Security capabilities Automated source analysis of v0.1.0 — what this tool can access: - **Network access:** no - **Filesystem access:** no - **Shell / process execution:** no - **Environment & secrets:** no - **Dynamic code execution:** no *"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.* ## Versions - **0.1.0** — security scan: passed — Imported from the upstream source. ## Links - Listing page: https://agentstack.voostack.com/l/skill-angad-kandhari-deliberate-debug - Seller: https://agentstack.voostack.com/s/angad-kandhari - Browse the marketplace: https://agentstack.voostack.com/browse --- Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.