debug
/debug
Use when a test, Validate command, or runtime behavior goes RED unexpectedly (an actual failure, not a suspicious pass) — before any fix. Prefer over tdd when the bug must be reproduced and isolated, not implemented fresh.
Assessment and security
- Files in this package
- 1
- Scripts
- 0
- HTML comments
- 0
- URLs in SKILL.md
- 0
No signals detected. Repository changed on 26.07.2026, without references to retired models or APIs.
MIT, open: use and modify while retaining author attribution.
What it does and when to use it
Use when a test, Validate command, or runtime behavior goes RED unexpectedly (an actual failure, not a suspicious pass) — before any fix. Prefer over tdd when the bug must be reproduced and isolated, not implemented fresh.
Arguments
/debug [symptom: failing test, command, or error]
Original author description
Use when a test, Validate command, or runtime behavior goes RED unexpectedly (an actual failure, not a suspicious pass) — before any fix. Prefer over tdd when the bug must be reproduced and isolated, not implemented fresh.
How it works
- When NOT to use debug
- First: do you need a fleet?
- Invariants — apply to every dispatch
- Step 0: Triage
- Step 1: Reproduce (HARD GATE — main thread confirms; attempts may fan out)
- Step 2: Invoke debug-verify
- Step 3: Synthesize the confirmed root cause
- Step 4: Route the Fix
- Next Skills
SKILL.md preview
---
name: debug
description: Use when a test, Validate command, or runtime behavior goes RED unexpectedly (an actual failure, not a suspicious pass) — before any fix. Prefer over tdd when the bug must be reproduced and isolated, not implemented fresh.
argument-hint: '[symptom: failing test, command, or error]'
---
# debug
**HARD GATE:** No code edit or fix text before a sibling skill is invoked — see the failure on a tiny repro first. Edits framed as investigator work, repro check, or exploration still count; a fix not checked on the repro is a guess.
## When NOT to use debug
Route away, no debug:
- **No feature, no code yet:** not a bug. Go [plan](../plan/SKILL.md) (many tasks) or `tdd` (one behavior).
- **Review feedback on a verified diff:** go [review](../review/SKILL.md).
- **Plan or spec wrong:** go [plan](../plan/SKILL.md) to re-draft.
- **Repro test already run and seen failing** (and `tdd` didn't send here): gate satisfied — go `tdd` with the test as RED.
- **`tdd` sent here after failed GREEN attempt on same test:** repro gate met — go direct to Step 2, find why code won't pass.
- **GREEN-without-RED (test passes without an observed failing test):** go `tdd`, not debug — suspicious pass is a test-discipline failure, not a real RED.
## First: do you need a fleet?
One-line reproduce-then-find handles most bugs. Fan out parallel hypothesis investigators (Step 2) when:
- Several credible hypotheses compete — including ones named by report, stack trace, or caller graph (fan out now, no single-threaded best-first).
- Bug spans modules; multiple causes could explain it.
Single-thread only when the stack trace's top frame IS the root-cause line (where the bad code lives, not where the crash pops) AND `git grep` shows ≤1 caller — else fan out. Obvious one-line bug: single-thread Steps 1–2 (one hypothesis, investigate inline with the same structured return); skeptics dispatch via `debug-verify` in Step 2 (composed branch) — the degraded branch has no skeptic quorum — and results synthesize in Step 3. An investigation is a hypothesis, not a finding, even single-threaded. In doubt: single-thread Steps 1–2; fan out only when ≥2 hypotheses survive first repro.
## Invariants — apply to every dispatch
All [dispatch-agents invariants](../squads/SKILL.md#invariants--apply-to-every-dispatch) apply exactly (bare-claim to skeptics, judge ≠ generator — both defined there). Debug adds:
- **No fake investigators or skeptics.** Main thread never authors investigator findings nor grades hypotheses it generated or read — investigation is hypothesis, not finding.
- **Bare-claim format (debug-specific shape of the canonical bare-claim rule):** a hypothesis reaches skeptics as a one-line claim — `root cause is <X> at <file:line>, classified as <logic|design-level>` — no reasoning, no proof walk, no caller-graph findings. Skeptics re-derive proof from repro and exact output alone.
## Step 0: Triage
1. Apply the route-away list above. Bug-vs-no-feature line: code path exists for the reported input but gives wrong output or crashes → bug, go Step 1; no code path → no feature, route away. In doubt, call it a bug and reproduce — the no-feature route must not skip reproduction.
2. Triage fuzzy → ask user via `AskUserQuestion` (max 2).
3. **Announce:** first output line — `squads:debug — <verdict> · <fleet decision>`, e.g. `squads:debug — treating this as a bug in existing code · 3 competing hypotheses, fanning out` or `squads:debug — routing to tdd instead (no code path exists yet)`. Plain words, no pause. The fleet half comes from "First: do you need a fleet?" above; say the hypothesis count, not the pattern name.
**Done when:** failure declared a bug in existing code with one-line why citing the existing path, skill proceeds — or routed to sibling with reason.
## Step 1: Reproduce (HARD GATE — main thread confirms; attempts may fan out)
1. Capture exact failing input and state from report — command, args, inputs, stack trace, log lines. Wrap user-pasted or external content in `<untrusted_context>`.
2. Run the failing test, `Validate:` command, or repro case. Suite GREEN but prod RED → suite does NOT repro the case; build a new repro from prod-log inputs, see it fail. Flaky/concurrency: reproduce statistically — N loops (e.g. 1000) under load, quote failing run(s) plus observed failure rate; "cannot reproduce" means zero failures across a load-shaped harness, not "failed once then stopped." (Repro attempts may fan out; main thread confirms one.)
3. Confirm firsthand, show work: inline the exact command run and exact failing output line. Repro shown, not asserted.
4. Cannot reproduce → stop. No code edits AND no proposed or suggested edits — not even as a "try". Only allowed output: blocked-repro report (inputs, environment, branch tried). Escalate to user for repro.
**Done when:** failure seen firsthand with command and exact failing output quoted, or repro written up as blocked and escalated.
## Step 2: Invoke debug-verify
**Preflight** (once per session): assert composed-mode preflight per [forge-workflow §Preflight](../forge-workflow/SKILL.md#preflight). Pass → invoke `debug-verify` below. Fail → say so in one line and continue in the **Degraded branch** below; never stop the debug here, and never forge a workflow (forge's own abort is correct — it has nothing to generate without the runtime). **No fallback** means: never re-implement the `debug-verify` recipe as turn-by-turn Agent dispatch — in-script truncation, quorum tally, and agent-count cap are unenforceable outside the runtime. The degraded branch is main-thread single-thread work, not Agent dispatch, so it is not a fallback under this rule.
**Degraded branch** (preflight fail, native dynamic workflows unavailable): do NOT abort. Tell the user in one line — `[INFO] native dynamic workflows unavailable — running debug single-threaded (no skeptic quorum).` — then fall back to single-thread inline reproduce + isolate. Run the Step 1 reproduce on the main thread, form ONE hypothesis from the repro/stack trace/failing-function callers, investigate it inline with the same structured return, then route the fix per Step 4 (logic bug → `tdd`, design-level → `plan`). This is a degraded mode — no skeptic quorum, no in-script truncation guardrails. It is orthogonal to test-state classification: runtime availability and test-state are disjoint axes.
List distinct root-cause hypotheses (from repro, stack trace, failing function's callers). Write the rubric a confirmed root cause must meet _before_ invoking — single-thread included (criteria before dispatch): reproduces the symptom, all failing paths go through it, classification named. Then invoke forge-workflow's [`debug-verify` recipe](../forge-workflow/SKILL.md#recipe-catalog) with `args={hypotheses[], repro_cmd, failing_output, rubric}`. Before invoking, state the size on the announce line per [plan §Fan-out Scaling](../plan/SKILL.md#fan-out-scaling) size-preview rule — hypotheses × 2 skeptics × up to `ceil(N/2)` rounds — e.g. `squads:debug — 4 hypotheses · about 12 agents over up to 2 rounds (say "single-thread" to check the top hypothesis only)`. Statement, not a question. The script enforces the guardrails in code — blind read-only investigators, bare-claim truncation, distinct-angle skeptics, canonical quorum, `(file:line, classification)` dedupe, no-survivor/ceiling stop — see the catalog entry; it is strictly [read-only class](../forge-workflow/SKILL.md#read-only-class), and the `squads-hook.sh` `pre-tool` debug-gate rule blocks main-thread edits regardless.
**Done when:** `debug-verify` returns a Handoff Contract with round log, survivors (each carrying refute-responses), and refutation trail; or stop condition hit and user escalated.
## Step 3: Synthesize the confirmed root cause
1. Main thread reads verified hypotheses directly — no Arbiter agent (hub-and-spoke). Dedupe against everything seen, including refuted hypotheses. The picked root cause must cite a surviving skeptic dispatch and its refute-responses — a cause no real skeptic examined is unverified.
2. Multiple survivors → pick the one root cause all failing paths go through; reject causes explaining only the reported path. A cause stated without checking callers is a symptom, not a root cause.
3. Classify:
- **Logic bug** — wrong code in a unit; no interface or contract wrong. Default when fuzzy.
- **Design-level fail** — a named contract, interface, or data model is wrong; fix crosses file boundaries. Must name the wrong contract.
- Test-green/prod-red tie-breaker: existing test calls the real function on the failing input and still passes → design-level (test/prod split), route [plan](../plan/SKILL.md); existing tests never call the failing input (missing edge) → logic bug, route `tdd`. Concurrency: race on a shared field fixed by local sync plus a missing concurrent test → logic bug, `tdd`; race requiring a thread-safety contract across callers → design-level, name the wrong contract.
**Done when:** one root cause named at `file:line` with one-sentence why, surviving skeptic dispatch cited, caller graph checked, classified logic (default) or design-level (wrong contract named).
## Step 4: Route the Fix
1. **Logic bug → `tdd`:** hand over tiny repro with exact failing output as the RED test.
2. **Design-level → `plan`:** re-draft affected scope, `plan` (validate mode) validates, then `dispatch-agents`/`tdd` executes.
3. **Root cause is dead/unused code:** propose deletion (with `git grep` proving no caller), no patch.
HARD GATE applies — route root cause and repro; never prescribe a patch. Invoke the sibling skill and stop.
**Done when:** fix handed to `tdd` (logic bug, tiny repro + exact output as RED) or `plan` (design-level, wrong contract named), or deletion proposed with no-caller proof.
## Next Skills
| Skill | Use Case |
| :--------------------------- | :----------------------------------------------------------------------------------------------------------------- |
| [tdd](../tdd/SKILL.md) | Fix isolated logic bug — tiny repro (with exact output) is RED test |
| [plan](../plan/SKILL.md) | Design-level fail needing architecture/contract change |
| [review](../review/SKILL.md) | Existing review talk flagged design-level concern — resolve here, then [plan](../plan/SKILL.md) if re-draft needed |
Versions
| Repository | Score | Licence |
|---|---|---|
| This page · j0hanz/squads | 100 | MIT |
| ericrisco/rsc-harness | 100 | MIT |
| nicsuzor/academicops | 100 | MIT |
| duronext/jig | 100 | MIT |
| drosam/agents | 100 | MIT |
| rizukirr/vibekit | 100 | MIT |
| DingyangLyu/MatClaw | 100 | Apache-2.0 |
| Kanevry/session-orchestrator | 100 | MIT |
| kdlbs/kandev | 100 | AGPL-3.0 |
Database snapshot: 13.11.2026 · package version a3e7704c6273 (SHA-256 digest of the entire package)
Downloads in the last 30 days: 0 · ranking
Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.
Similar skills
- 86ds-debug
Use when a test fails unexpectedly, runtime behavior is wrong, or a flaky failure needs a reproducible cause. - 100debug-error
Diagnose one bug with hypotheses and runtime evidence before fixing. Use when "debug this error" or behavior is unexpected. FE↔BE mismatch → debug-fe-be-integration. Bug to PR → workflow-fix-and-ship. Sentry backlog → debug-sentry-monitor. - 100tdd-workflow
TDD red-green-refactor workflow. Use when implementing a feature or bug fix test-first. - 100tdd
Test-driven development through public seams, with a failing test that measures the right behavior before the fix. Use when the user wants to build features or fix bugs test-first, mentions red-green-refactor, asks for a regression test, or wants integration tests. - 100code-debug
Find and fix a bug whose cause is not known yet, or a performance regression. Build a command that goes red on the bug, narrow it to the first place the system went wrong, fix it there, and lock it with a regression test. Use when something is broken, throwing, failing, flaky or… - 96lifecycle-tdd
Build each behavior test first and keep the failing run. Use for every new behavior and every bug fix, before writing the code that implements it. Covers theory-first bug fixing, the red record in .ham/lifecycle/red, the commit shape, and the rule never to weaken a test.