Best root-cause debugging skills to hand your AI agent

An agent debugging on instinct thrashes. It reads the error, guesses at a cause, edits a line, reruns, guesses again — and three edits later the original symptom is buried under new ones. It "fixes" the place the exception surfaced instead of the place the bad value was born. It declares victory without ever reproducing the failure, so the bug comes back the next time the inputs shift. On a long session it loses the thread entirely, re-testing hypotheses it already ruled out. The skills here exist to replace that instinct with a procedure.

What surprised me on reading them: the most-copied "systematic-debugging" skills are, to the line, the same document. One MIT original — Jesse Vincent's "Iron Law" — has been forked and re-forked across publishers, sometimes credited, sometimes copied without a license. The name tells you almost nothing. What separates a good pick from a redundant one is what each fork added: a feedback-loop-first rule, a ranked set of hypotheses, a structured report, a prompt-injection boundary. And a distinct minority throw out the single-threaded phase gate altogether for parallel, competing-hypothesis investigation. Pick on the additions, not the name.

Top picks

The through-line in all of these is one rule: no fix before the root cause is confirmed. Where they diverge is how hard they make the agent work to earn that confirmation, and whether one agent walks the process or several do.

Start with obra's original — it's the source the others copy

obra/superpowers/systematic-debugging is the canonical Iron Law: "NO FIXES WITHOUT ROOT CAUSE INVESTIGATION FIRST," then four phases the agent completes in order — investigate, find the pattern, write one hypothesis ("I think X is the root cause because Y"), fix behind a failing test. Its sharpest instrument is the Rule of Three: after three failed fixes, stop and question the architecture, because each new fix surfacing a fresh problem somewhere else means the pattern is wrong, not the code. A Common Rationalizations table pre-empts the excuses an agent talks itself into.

It leans on companion files it references — root-cause-tracing, defense-in-depth — that you'll want installed alongside it, and its "you're doing it wrong" signals assume a human partner. It's the floor, not the ceiling.

Install NousResearch's fork instead if you want one systematic-debugging skill

NousResearch/hermes-agent/systematic-debugging labels itself "adapted from obra/superpowers," and the adaptation is real work. It adds a Feedback Loop Rule that puts building a red-capable reproduction before reading code, with ten ways to construct one — failing test, curl script, replayed trace, git bisect harness, differential loop. It swaps obra's single hypothesis for three-to-five ranked, falsifiable ones, each stated as a prediction. It prefers a debugger to logging ("one breakpoint beats ten logs") and tags temporary logs with a unique prefix so cleanup is one search.

The caveat: some action blocks name Hermes-specific tools (search_files, delegate_task), so you're porting those to your agent. The method underneath is portable, and it's the better-built of the two.

Reach for wshobson's parallel-debugging when the cause could be several things

wshobson/agents/parallel-debugging trades the linear phase gate for Analysis of Competing Hypotheses. It seeds hypotheses across six failure-mode categories — logic, data, state, integration, resource, environment — then runs them as rivals, not a to-do list. Its best feature is an evidence-strength table that rates a file:line reference as strong and "it works on my machine" as explicitly weak testimonial, forcing every claim to cite a location. An arbitration protocol then sorts hypotheses into confirmed, plausible, falsified, or inconclusive.

It presumes a reproduction already exists — its validate step checks the original case no longer fails but never teaches you to build one. Pair it with a repro-first skill; use it to adjudicate, not to reproduce.

Use Dimillian's bug-hunt-swarm to keep the agent's hands off the code

Dimillian/Skills/bug-hunt-swarm is diagnosis-first and emphatic about it: four read-only sub-agents investigate in parallel — reproduction and scope, the failure seam, recent regressions, a proof plan — and the order that each "must not edit files, apply patches, or make any other workspace changes" is repeated for every one. The main agent merges their findings into ranked hypotheses and a diagnosis grouped as prove now, fix next, follow up later.

Because it never fixes anything, you need a separate skill for the repair — that's the point, not a gap. It also tells you to skip the swarm on "a tiny and obvious issue," the right instinct to encode. Best when a bug spans modules and you don't yet know which one is lying.

Add secondsky's root-cause-tracing as the companion that finds the source

secondsky/claude-skills/root-cause-tracing is the backward-tracing technique obra's skill defers to a companion file for — obra points at its own root-cause-tracing.md, and this is a copy of it. When an error surfaces deep in the stack, trace backward through the call chain to the original trigger and fix there, not where it blew up. It walks a real example — an empty projectDir that silently resolves to process.cwd() and inits git in your source tree — then shows the instrumentation move: capture new Error().stack and log with console.error (not a logger, which tests suppress) before the dangerous operation, and bisect the suite to find which test pollutes.

It's a single tool, not a workflow, and its examples are TypeScript-flavored. Install it beside whichever full method above you choose.

skill	publisher	license	verdict	updated
systematic-debugging	obra	MIT	The source original; solid floor	2026-07-24
systematic-debugging	NousResearch	MIT	Better-built fork; top pick	2026-07-28
parallel-debugging	wshobson	MIT	For many-cause bugs	2026-07-22
bug-hunt-swarm	Dimillian	MIT	Read-only parallel diagnosis	2026-03-29
root-cause-tracing	secondsky	MIT	Backward-trace companion	2026-07-25
gstack-openclaw-investigate	garrytan	MIT	Iron-Law variant with a report	2026-07-15

Why do so many skills share the name systematic-debugging?

Because skill names aren't namespaced. A name is a topic, not an address, so the same string covers completely different documents. Vincent's MIT original spread by copying: some publishers credit it and extend it honestly — jamditis/claude-skills-journalism/systematic-debugging names the source, adds a research phase, and wraps retrieved material in an untrusted-content boundary that treats logs and API responses as data, not instructions; moltis-org/moltis/systematic-debugging records its origin as a fork of the Hermes fork; FradSer/dotclaude/systematic-debugging repackages it as a slash command with a bail-out that skips the whole pipeline when you've already named the root cause and the one-line fix.

Others just copy the text. mrgoonie/claudekit-skills/systematic-debugging carries the original's exact wording with no license attached. Even the tells hide in worked examples: PracticalSwan/agent-skills/root-cause-tracing still prints /Users/jesse/project in its trace — Jesse Vincent's own path — while secondsky's copy sanitized it to ~/project. And garrytan/gstack/gstack-openclaw-investigate proves the inverse: a different, odd name over the same Iron-Law method, this one adding a structured DEBUG REPORT saved to memory and an external-search step that strips hostnames, IPs, and customer data before you paste an error into a search box. The lesson: the publisher plus the body is the identity. Open the body before you install, and let the name be nothing more than what shelf to look on.

What to check before you install one

Four things the card won't tell you. License: the MIT original is freely reusable; several of the most-copied versions ship the same text with no license, which is a reuse risk, not a quality signal. Diagnosis-only or hands-on: a swarm or tracer that refuses to edit code needs a separate fix step; a full four-phase skill writes the fix and the regression test itself. Toolchain coupling: some skills assume a specific stack — Hermes tool names, a ccw CLI, a Chrome DevTools MCP — and quietly degrade without it. Referenced companions: the best of these point at sibling files like root-cause-tracing and defense-in-depth; check those are actually in the folder you install, or the method has holes where the pointers were.

The bottom line

The failure mode is an agent that edits before it understands, patches the symptom, and calls a bug fixed without ever reproducing it. Every pick here answers that with the same rule — root cause before fix — and differs only in rigor and shape. NousResearch's fork is the strongest single skill: it makes the agent build a reproduction before it reads code and rank its hypotheses before it tests one. When a bug has many plausible causes, wshobson's competing-hypotheses framework adjudicates them; when it spans modules, Dimillian's read-only swarm diagnoses without touching the code. Add secondsky's backward-tracer so the fix lands at the source. Then the name on the shelf stops mattering — the procedure does.