| name | debug |
| description | Use when encountering a bug, test failure, or unexpected behavior — runs staged investigation before implementing any fix. |
| user-invocable | true |
| tier | rigid |
| kind | process |
Run: `bash "$(git rev-parse --show-toplevel)/bin/harness-update-check"`
- `UPGRADE_AVAILABLE ` → tell the user: "agent-harness is available (you have ). Run `/harness-update` to pull it in." Then continue.
- `JUST_UPGRADED ` → tell the user: "agent-harness upgraded → ." Then continue.
- No output → continue silently.
/debug
Override: see CLAUDE.md § Instruction precedence. The user is principal; this skill is advisory.
Staged debugging: root cause → pattern analysis → hypothesis + minimal test → handoff. /debug doesn't write the fix; it hands off to /tdd after Phase 3 confirms the hypothesis.
The Iron Law
NO FIX WITHOUT ROOT CAUSE NAMED AND HYPOTHESIS VALIDATED
A fix without evidence is a guess. "Let me try one more thing" means you've been guessing. After 3 failed implementations, stop and question the architecture.
The Four Phases (strict order; each has a gate)
Track attempts via TodoWrite — every fix attempt is one todo, completed on verify/revert.
- Root cause. Read the actual error output (not just the FAIL line). Reproduce locally. Check recent changes (
git log --since=..., git diff main...HEAD). Log inputs/outputs at component boundaries until you see the value go wrong. Gate: one-sentence hypothesis with file:line evidence, or stop and ask the user.
- Pattern analysis. Find a working example of the same code path — elsewhere in this repo, in a sibling test, in OSS. Name the differences. Gate: differences listed in writing.
- Hypothesis + minimal test. Pick the smallest change that would prove the hypothesis (a
console.log, an isolated unit test, a one-line expression). Change ONE variable at a time, run in isolation. Gate: hypothesis confirmed by evidence, or a new (narrower) hypothesis stated.
- Implementation handoff. Hand off to
/tdd: "Root cause: <one sentence>. Confirmed by <evidence>. Failing test captures <assertion>." /debug ends here. Do NOT write the fix; do NOT invoke other implementation skills.
Attempt counter — architecture escalation at 3
After 3 failed implementations, stop. Don't try a 4th fix. Write down each attempt + why it failed; explicitly ask: Is the bug here, or is the design wrong? Read adjacent code with that lens; ask the user before continuing.
Three failures = the bug is not where you're looking.
Red Flags — STOP
REQUIRED SUB-FILE: Read red-flags.md for the full list (evidence-skipping, guess-as-fix, test-blame, phase-skipping, sunk-cost, authority pressure). The most common: "Must be flaky," "Let me try one more thing," "Just retry the test," "Mark it .skip()." All mean: stop. Read the actual error. Name the root cause before any next step.
Common Rationalizations
REQUIRED SUB-FILE: Read rationalizations.md if you find yourself making excuses. The verbatim-excuse-to-reality table is anchored in the debug-thrash baseline (where the load-bearing distinction is guessing vs debugging — a fix without evidence is a guess).
Self-Review Checklist
Cannot check all boxes? You skipped a phase. Restart from the unmet gate.
What this skill does NOT cover
Writing the fix (use /tdd), production incident triage (use /incident, which hands off to /debug after root cause), and architectural redesign (propose as a separate workstream after the 3-attempt escalation).
