Debug

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.From its SKILL.md

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.

2 things 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.
runs commandsInstructs the agent to run 1 command, including `git bisect`.

SKILL.md

3.8 KB, 869 tokens by cl100k_base, 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.

What ships with it

Read from the repository

Just SKILL.md. No reference files, no scripts.

Gives 0 of the 12 instructions most test skills give in 869 tokens

Counted across 1,201 of the 2,096 authors here whose files we hold, read 2026-09-06

Write a failing test before writing codein 43 of 1201, across 36 files
Run the full test suitein 36 of 1201, across 35 files
Test only one variable per experimentin 34 of 1201, across 17 files
Read product marketing context before asking questionsin 34 of 1201, across 14 files
Mock external dependenciesin 34 of 1201, across 30 files
Define primary, secondary, and guardrail metricsin 33 of 1201, across 16 files
Pre-determine sample size before startingin 31 of 1201, across 14 files
Test behavior rather than implementationin 31 of 1201, across 29 files
Formulate a hypothesis before designing a testin 30 of 1201, across 13 files
Document every test hypothesis, variant, and resultin 29 of 1201, across 11 files
Use descriptive test function namesin 25 of 1201, across 21 files
Commit to the methodology without stopping earlyin 24 of 1201, across 8 files

Said here and by no other author read

create a fast deterministic pass fail signal
tag all diagnostic probes with a unique marker
measure performance regressions with quantified baselines
force flaky bugs to reproduce reliably
remove all debug probes after verification

Grouped from the skills themselves: near-identical wordings counted once, and counted by distinct author, so one author publishing three of these counts once. Length counted with cl100k_base; the agent that loads this file may tokenize it differently.