rig-debug

Debug

Drive a bug to root cause and a single minimal fix using the four-phase methodology.

Configuration

Reads .rig/config.json:

• test.command — how to run the test suite when collecting Phase 1

evidence (default: npm test).

• agents.debugger — the project's name for the canonical debugger

role (default: rig-debugger).

• agents.architect — the project's name for the canonical architect

role, used only when escalating (default: rig-architect).

• style.guideFile — the writing style for the report you hand back

(default: .claude/STYLE.md).

If the file is absent, use the defaults above and note you're running unconfigured.

The four-phase methodology

The debugger agent runs this loop; the skill drives it and refuses to let it skip ahead. Each phase has a deliverable that gates the next:

• Phase 1 — Root cause. Gather evidence: reproduce the failure, read

the failing code path, capture the exact error/stack/trace, git diff the suspect window. Deliverable: a stated root cause backed by observed evidence — not a guess.

• Phase 2 — Pattern analysis. Find a similar code path that works and

list every difference between it and the failing one. Deliverable: the list of differences.

• Phase 3 — Hypothesis. State the specific change that should fix the

root cause and why, plus how you'll confirm it. Deliverable: one falsifiable hypothesis.

• Phase 4 — Minimal fix. Apply the smallest change that addresses the

root cause, add/extend a test that fails before and passes after. Deliverable: root cause + fix + test.

Arguments

$ARGUMENTS is a one-line description of what's broken. Examples:

• test suite fails with a database connection-closed error
• the workspace-commit step times out on a fresh worktree
• PR #519 deprovision workflow leaves orphaned resources behind

If $ARGUMENTS is empty, ask the user for the symptom in one sentence. Don't start the loop on a vague brief.

How it runs

1. Print the brief. Restate the bug in one line so the user sees

you understood it correctly.

1. Spawn the `debugger` agent (mapped through agents.debugger) with

the brief, the working directory (current cwd), and any obvious context (the failing test name, the production trace ID, the relevant ticket). Tell it to start at Phase 1 and not propose fixes until Phase 1's deliverable is in.

1. Read the agent's report. It comes back at one of these states:

• Phase 1 incomplete — need <data> → either run the data

collection yourself (run the test command from .rig/config.json (test.command, default npm test) scoped to the failing test, fetch logs, git diff) or ask the user. Then re-spawn the debugger with the data added.

• Phase 4 complete — root cause, fix, test → done. Report to

user with the agent's output. The fix is already in the worktree.

• Three fixes failed — architectural concern → stop here and surface

the agent's architectural-concern note to the user. Another debugger run with "try one more thing" repeats the pattern. Suggest re-scoping or pulling in the architect agent (mapped through agents.architect) for a design review.

1. After a Phase 4 fix, hand back to the user. Don't auto-PR.

Debugging produces a candidate fix; the user decides whether to ship it.

Anti-patterns this skill exists to prevent

• Coder agent invoked on a bug with "fix this" — coder writes a

plausible patch with no root cause. Bug returns later.

• Multiple speculative fixes piled into one commit. Can't tell what

worked, can't revert cleanly.

• Architectural problems repeatedly patched at the symptom layer

until they metastasize.

Relationship to other skills

• Use `/rig-debug` when you don't know why something fails. It refuses

to guess.

• Use an implement-style flow when you know what to build. It assumes

the spec is correct.

• Use a verify flow to confirm a known-good change works end-to-end —

not for debugging an unknown failure.

• /rig-debug may end with a follow-up ticket if the fix is big enough to

warrant one; usually it just ends with a small worktree change the user reviews directly.