Debug

Install

npx -y skills add vasu-devs/Forge --skill debug

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

1 stars1 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.

What its author says it does

Copied from the file, not written here

Find the root cause of a bug, test failure, or performance regression before proposing any fix. Use the moment something is broken, throwing, failing, flaky, or slower than expected — and resist the urge to patch first.

SKILL.md

3.8 KB, as published. Nobody here has run it

██████╗ ███████╗██████╗ ██╗   ██╗ ██████╗
██╔══██╗██╔════╝██╔══██╗██║   ██║██╔════╝
██║  ██║█████╗  ██████╔╝██║   ██║██║  ███╗
██║  ██║██╔══╝  ██╔══██╗██║   ██║██║   ██║
██████╔╝███████╗██████╔╝╚██████╔╝╚██████╔╝
╚═════╝ ╚══════╝╚═════╝  ╚═════╝  ╚═════╝

Debug to root cause

The Iron Law

No fix without a root-cause investigation first. A patch applied to a symptom you don't understand usually moves the bug rather than removing it.

The feedback loop IS the skill

Everything else is mechanical. Your first job is a fast, deterministic pass/fail signal for the bug. Build the best one you can afford, preferring higher rungs:

A failing automated test that reproduces it (best — becomes your regression test)
A one-shot command: curl, a CLI invocation, a script with a snapshot diff
A tiny harness that exercises the path
Manual reproduction with logged output (last resort)

A 2-second deterministic loop is a debugging superpower; invest in it before theorizing. If you can't reproduce it, that's the bug to solve first. (Prefer the earliest rung you can manage — 1 is best.)

Hypotheses: plural and falsifiable

Don't anchor on the first idea. Write 3-5 ranked hypotheses, each with a prediction you can test ("if it's a caching issue, then clearing the cache fixes it; if it's a race, then adding a delay changes the outcome"). Instrument to discriminate between them, not just to confirm a favorite.

Tag every diagnostic probe you add with a marker like [DEBUG-a4f2] so cleanup at the end is a single grep — never leave instrumentation behind.

The 3-fixes rule

If you've tried 3 fixes and the problem keeps reappearing somewhere new, STOP. Do not attempt fix #4. Cascading symptom-fixes mean your mental model of the architecture is wrong — discard the current hypotheses and re-derive them against the structure, not the symptom. (Your human's tells — "stop guessing", "ultrathink this", "why does this keep happening" — are the same signal: restart at root cause.)

Name the cause before you fix

Before writing any fix, state it in one sentence: this symptom is caused by X, via mechanism Y. If you can't, you haven't found the root cause — keep instrumenting. The fix must target X, not the place the symptom surfaced.

Performance and flaky bugs use a different loop

Performance regressions: measure, don't theorize. Capture a quantified baseline and a target delta, profile to find the real hot path, and use git bisect to find the commit that introduced it. "Feels slow" is not a signal; a number before/after is.
Flaky / non-deterministic bugs: there's no 2-second deterministic signal yet, so manufacture one — run the case N times and measure the failure rate, then force it to reproduce reliably (loop the test, inject delays, fix the seed, enable a race detector) before fixing. A fix you can't show drives the failure rate to 0 over N runs is not verified.

Close the loop

Once you've found and fixed the root cause, the reproducing test becomes a permanent regression test (hand to forge:tdd if it isn't already a test). Remove all [DEBUG-] probes. Then forge:verify with the now-green test as evidence.