debugduck

debugduck

A debugging skill for Claude Code, Cursor, and any other coding agent that can read a markdown file. It runs the same procedure in any codebase.

The loop it enforces:

Reproduce, observe, localize, explain, fix, prove.

It covers frontends, backends, libraries, services, CLIs, browser extensions, GitHub apps, data pipelines, and mobile apps. That range is possible because the procedure operates on evidence and search space instead of framework specifics. Tracing a wrong value backwards to the line that produced it is the same operation whether the value is a React prop or a row in a Spark job.

Why

Ask an agent to fix a bug and it will usually read the stack trace, pattern-match something plausible, edit a file, and tell you it is done. Sometimes that works. When it doesn't, you get a fix that papers over the symptom, or a fix for a bug that was never there, plus one or two new ones you won't find until later.

Three failure modes come up constantly:

It also insists on the two steps everyone skips when they are in a hurry: deleting the debug logs afterwards, and checking whether the same mistake exists elsewhere in the repo.

Trace the whole path in one pass

This is the flow I use, and the one the skill defaults to. When I hit a bug, I ask the agent to put log statements at every strategic point from A to Z, with the values I actually care about, then I run it once and hand the output back. It usually finds the bug in one or two shots.

That cuts against the standard advice, which is to bisect. Bisection minimizes the number of probes, and it is the right call when a probe is cheap. For an agent a probe is not cheap. Each one costs an edit, a run, and a human pasting output back into the chat. Eight probes means eight of those, with eight chances to lose the thread. A full trace costs one, and instead of a single bit per probe you get the entire execution history to read.

Four things separate a trace that lands in one shot from one that takes three.

The agent writes down what each checkpoint should print before you run anything. Finding the bug is then mechanical: the first place where actual and expected disagree is where it lives. Without predictions you are scanning logs for something that looks off, which is guessing with extra steps.

Checkpoints are numbered, CP01 through CPnn. If the output jumps from CP06 to CP09, execution never reached CP07, and you have located the problem without reading a single value.

The agent stops once it has instrumented, and hands you the run command. Left alone it will instrument and then guess at a fix in the same message, which throws away the whole technique.

Everything upstream of the divergence comes out proven innocent, and the skill writes that down, so nothing gets re-examined an hour later.

Then there is the unglamorous half that decides whether any of this survives contact with real code: capping output inside loops so the trace doesn't drown, correlation ids so concurrent work stays readable, redaction rules because you are about to paste this into a chat window, and one grep tag per investigation so cleanup is a single command you can verify.

Full protocol in skills/debug/references/trace-first.md. Bisection is documented as the fallback, for when you can't re-run the code, when adding logs makes the bug disappear (which means it is a race, and you should widen the window instead), or when git bisect run would just find the commit while you do nothing.

Install

Claude Code

git clone https://github.com/ujjwal502/debugduck.git
cd debugduck
./install.sh                           # ~/.claude/skills/debug, available everywhere
./install.sh --project /path/to/repo   # <repo>/.claude/skills/debug

Or copy skills/debug/ into ~/.claude/skills/ by hand for personal use, or into .claude/skills/ in a repo to commit it and share it with your team.

Claude Code picks it up on its own when you describe a bug. To invoke it directly: /debug the login flow 500s on Safari only.

Cursor

./install.sh --cursor /path/to/repo

That installs .cursor/rules/debug.mdc, a condensed version of the procedure that attaches itself when you mention a bug, alongside the full reference files under skills/debug/ which the agent reads on demand.

Everything else

./install.sh --agents /path/to/repo

This copies the skill into the repo and adds a pointer to AGENTS.md, which Windsurf, Cline, Codex, Zed, Aider and most others read automatically. For anything that doesn't, point its rules file at skills/debug/SKILL.md. There is no tool-specific syntax anywhere in the content, so it works wherever a model can read a file.

What's in it

skills/debug/
├── SKILL.md                    the procedure: prime directives, the six phases,
│                               hypothesis ledger, assumption audit, symptom lookup table
└── references/
    ├── trace-first.md          full-path instrumentation, the default localizer:
    │                           map, predict, instrument, run, read the first divergence
    ├── techniques.md           bisection over code, history and input; delta minimization;
    │                           differential debugging; tracing back from the symptom
    ├── instrumentation.md      logging that pays off, debuggers, stack dumps from a hung
    │                           process, tracing, profiling, and the cleanup checklist
    ├── heisenbugs.md           flaky, racy, order-dependent, timing-dependent, CI-only
    ├── postmortem.md           toggle test, regression tests, sibling bugs, blast radius
    └── stacks/
        ├── frontend.md         rendering, state, hydration, events, CSS, network
        ├── backend.md          HTTP, DB, auth, caching, queues, production incidents
        ├── library.md          packaging, module formats, versions, "works for me"
        ├── browser-extension.md   MV3 service workers, content scripts, messaging
        ├── github-app.md       webhook delivery, app tokens, permissions, Actions
        ├── cli.md              args, stdio, exit codes, PATH, cron, packaging
        ├── data.md             pipelines and ML: schema drift, nulls, silent corruption
        └── mobile-desktop.md   lifecycle, permissions, native bridges, release-only bugs

SKILL.md is the entry point and stays deliberately small. The agent pulls in only the reference files that match the bug in front of it, so a CSS problem never drags in Kafka trivia.

The rules, condensed

If you read nothing else, this is what the skill enforces:

1. Reproduce before you diagnose. Diagnose before you fix.
2. The bug is where the evidence points, not where it would be convenient.
3. One variable at a time.
4. Trace the whole path in one pass and read the first divergence. Bisect over code, history, input, config or the timeline when you can't re-run.
5. A root cause explains all of the observed evidence, including the parts you'd rather ignore.
6. Prove the fix by toggling it off and watching the bug come back.
7. Never suppress a symptom you don't understand.
8. Label every claim as observed, inferred, or assumed.

When three hypotheses have been refuted, the skill stops generating a fourth and runs an assumption audit instead. The first question on that list is whether you are even running the code you think you are.

Getting good results out of it

Paste the whole error. The whole stack trace, the whole CI log, not the first line. Evidence collection is the first phase, so starting it with evidence in hand saves a round trip.

Ask for the trace directly when you already know roughly where the problem lives: "instrument the path from the login handler to the 401 and tell me what to run." You will get numbered checkpoints, a table of what each one should print, and a command. Paste the output back and the diagnosis usually follows immediately.

Say what you have already ruled out. It goes into the ledger under RULED OUT and stops the agent re-testing your dead ends.

Let it ask questions. If it says it can't reproduce the bug and needs a payload or a log line, that is the procedure working correctly rather than the agent stalling.

Read the closing report. It ends with root cause, evidence, fix, verified, and not fixed. If the verified section doesn't mention a toggle test, ask for one before you believe it.

About the name

Rubber duck debugging works because saying the problem out loud forces you to be precise, and precision is usually where the bug surfaces. This skill does the same thing mechanically. It makes the agent write down what it expects every checkpoint to print before running anything, and label each claim as observed, inferred, or assumed. Same instinct, written down instead of spoken.

The skill itself installs as debug, not debugduck, so the command stays /debug and the install path stays ~/.claude/skills/debug.

Contributing

Playbooks are the easy contribution. If your stack isn't covered, whether that's Rust, Unity, embedded, Salesforce or Kubernetes operators, add references/stacks/<name>.md and link it from the table in SKILL.md. Keep the entries concrete: a symptom, where to look, and the command that shows you. Anything that reads like generic advice, "check your code carefully" being the canonical example, should be cut.

License

MIT. See LICENSE.