Skip to content
Skills Library
Programming · Testing

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.

Repository
squads ↗
Licence
MIT
Last repository change
26.07.2026

Assessment and security

100/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
1
Scripts
0
HTML comments
0
URLs in SKILL.md
0
Deprecation

No signals detected. Repository changed on 26.07.2026, without references to retired models or APIs.

Licence

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

  1. When NOT to use debug
  2. First: do you need a fleet?
  3. Invariants — apply to every dispatch
  4. Step 0: Triage
  5. Step 1: Reproduce (HARD GATE — main thread confirms; attempts may fan out)
  6. Step 2: Invoke debug-verify
  7. Step 3: Synthesize the confirmed root cause
  8. Step 4: Route the Fix
  9. Next Skills
Original SKILL.md headings · 88 lines, 1,490 words
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

RepositoryScoreLicence
This page · j0hanz/squads100MIT
ericrisco/rsc-harness100MIT
nicsuzor/academicops100MIT
duronext/jig100MIT
drosam/agents100MIT
rizukirr/vibekit100MIT
DingyangLyu/MatClaw100Apache-2.0
Kanevry/session-orchestrator100MIT
kdlbs/kandev100AGPL-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.

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.