Debug loop

Skill ayaqen/Agents-Scripts/skills/debug-loop

Hypothesis-driven debugging: reproduce, isolate, prove the cause before writing the fix.From its SKILL.md

Install

npx -y skills add ayaqen/Agents-Scripts --skill debug-loop

Assembled from the repository path, not quoted from the project. Check it against their README if it does not work.

One thing to look at

2 stars2 stars. Stars are a popularity signal and not a quality one, but at this level it is likely that nobody has read this closely except its author, and you would be relying on your own review.

SKILL.md

1.9 KB, as published. Nobody here has run it

debug-loop

A disciplined loop that finds root causes instead of chasing symptoms. The core rule: never write a fix for a bug you cannot yet reproduce and explain.

When to use

A test fails and the cause isn't obvious within a minute of reading.
A bug report arrives without a reproduction.
A fix you already tried didn't work — that's the signal to stop patching and start this loop.

Workflow

Reproduce. Get a failing command you can run in under a minute. If reproduction takes a whole suite, narrow it: single test file, single test, then a minimal snippet. No reproduction → gather more evidence (logs, versions, inputs), don't guess.
State a hypothesis. One sentence: "X fails because Y." Write it down — vague hunches don't count and can't be falsified.
Design the cheapest experiment that can prove the hypothesis wrong: a targeted log line, a debugger breakpoint, git bisect, commenting out a code path, feeding a crafted input.
Run it. Hypothesis survives → strengthen it with one more independent check. Hypothesis dies → write down what you learned, form the next one. Keep the list; it prevents circling.
Prove the cause. You're done diagnosing when you can make the bug appear and disappear by toggling the one thing you claim is responsible.
Fix and lock it in. Apply the fix, re-run the original failing command, then add the regression test (see regression-fix).

Pitfalls

Changing two things between experiments — you learn nothing attributable.
"Fixed it, not sure why" — that's a symptom patch; the bug will return wearing a different hat.
Debugging on top of a dirty tree or the wrong branch. git status -sb first, always.
Skipping step 6's re-run: verify against the original failure, not just your reduced case.