ds-debug

/ds-debug

"Fix the bug" without a reproduction produces a plausible edit that fixes nothing, a test written after the fact that never went red, and a second incident a week later. This skill starts from an observed failure, narrows it mechanically, tries at most three hypotheses, and ships the smallest fix that turns the regression test from red to green.

Bug Hunter — reproduce → localize → hypothesize (≤ 3) → minimal fix → red-proven regression test → done gate.

Completion Evidence — applies to every phase: Report done/OK only with the machine-checkable evidence the gates name — the exact command run and its observed output (or file:line diff). Missing evidence → report INCOMPLETE plus what is missing. Self-assessment is never evidence. (This band repeats at file end by design — both copies are normative.)

Triggers

• User runs /ds-debug
• User reports a failure: "this test fails", "X returns the wrong value", "it crashes when…", "fix bug #N"
• A ds-build unit stays red after its approaches are exhausted and hands the diagnosis here
• CI or a check is red and the cause is unknown

Triggers — INVOKE / DON'T INVOKE

INVOKE	DON'T INVOKE
"why does parseMoney('1,234') return NaN — fix it"	"review the code for bugs in general" (→ ds-review)
"the test suite went red after the last commit"	"make the tests pass" by editing assertions (never — that is test weakening)
"reproduce and fix issue #7"	"implement feature #8" (→ ds-build)
"flaky test in CI"	"optimize this slow function" (→ ds-review --perf or ds-tune)
"crash on startup in production"	"set up error monitoring" (→ ds-deploy)

Contract

Dimensions: none (carrier)

• Fixes the observed failure and nothing else; unrelated defects found on the way become findings with a disposition, never silent edits.
• Standalone. Reads the repo, its tests, logs and git history; web lookups only under --research (ds-research when present, inline search otherwise), each fact cited.
• Full accounting enforced: every finding and planned check ends in an explicit disposition (fixed / skipped + reason / only you can do); summary totals balance.
• Pre-existing / out-of-scope errors detected during work are NOT skipped — fixed inline or escalated with concrete blocker.
• The red comes first. No edit before the failure is reproduced by a command whose output is pasted; a report that cannot be reproduced ends as not reproduced with what was tried — never as a speculative fix.
• Tests are never weakened. The regression test asserts the intended behavior from the report; an existing test that encodes the bug is corrected to the intended behavior and the change is stated. Assertion strength, expected values and coverage of the failing path never shrink.
• Checkpoint (../core/checkpoint-protocol.md): git status --porcelain before the first write; a dirty path the fix would touch → only you can do (commit or stash first); experiments are reverted per file with git checkout -- {file}, never a tree-wide reset. git bisect runs only on a clean tree and always ends with git bisect reset.
• Mechanical Done Gate: {check-cmd} (ds-quality arm when installed, else the stack-native chain from ../core/toolchains.md) captured at baseline, re-run after the fix and once before close; new red → fix ≤ 3 attempts, then revert and record; baseline red reported red-at-baseline; no tooling → Verification-Infrastructure Gap surfaced.
• Hypothesis budget: at most three hypotheses, each with a prediction, the test that would falsify it, and the observed result; a fourth is not tried — the run reports the three falsifications and stops with options.
• Publishing (push, PR, release) is never done here — only you can do with the command (../core/ask-exception-list.md). State-exempt: the failing test, the commit and the issue are the durable record.