Use when encountering any bug, test failure, build break, or unexpected behavior — runs a 4-phase systematic debugging process before proposing any fix. Iron Law: NO FIXES WITHOUT ROOT CAUSE INVESTIGATION FIRST. Produces a `.orchestrator/debug/` artifact the fixer agent must reference.
SkillScore50Maintained
Automatic
◆Coding pack
Last verified 8/17/2026
What it changes
Passed 6 of 12 test cases with the skill, and 4 of 12 without it.
Without skill32%
With skill50%
Checks it passed that the model alone missed
The response assigns a confidence rating to the chosen single hypothesis.
The response limits the hypothesized root cause section to exactly one sentence.
The response stops at Phase 0 and invokes `skills/bootstrap/SKILL.md` without proceeding to Phase 1.
and 3 more in the full report
5 fixed6 passed either way10 still failing1 broke
Pass-rate lift
+18 pp
Tokens
+81%
Agent turns
0%
Response time
-26%
Model gemini-3.6-flashMeasured 8/17/2026v411 of 22 cases passed with skill · 12 comparable
Tokens, turns and time describe resource use, not a dollar price.
See it in action
One of 4 test cases the skill fixed. Same model, same prompt, with and without the skill.
1 of 4
Prompt
A `code-implementer` agent was assigned a bugfix task by `wave-executor` regarding a crash in `src/services/billing.ts`. The agent wants to start editing `billing.ts` immediately. What prerequisite must be in place?
What was checked, without and with the skill
Checked
Without skill
With skill
The response requires referencing an existing Phase 1 debug artifact path in the task description before editing production code.
Missed
Passed
case-15 · gemini-3.6-flash · 8/17/2026 · answers are capped and redacted
What's inside
The instructions your model reads when the skill loads.
SKILL.md180 linessingle file
Debug Skill
4-phase root-cause investigation. Iron Law: no fix without root cause.
When to use
Any test failure (unit, integration, E2E)
Build break or compile error
Runtime exception in production code
Performance regression
Integration issue between modules
"It worked yesterday" bugs
When NOT to use
Feature implementation (use /plan or wave-executor)
Pure refactoring with no broken behavior
Style/lint fixes with no behavioral impact
Phase 0: Bootstrap Gate
Read skills/_shared/bootstrap-gate.md and execute the gate check. If the gate is CLOSED, invoke skills/bootstrap/SKILL.md and wait for completion before proceeding. If the gate is OPEN, continue to Phase 1.
The Iron Law
NO FIXES WITHOUT ROOT CAUSE INVESTIGATION FIRST.
No matter how obvious the fix looks, complete Phase 1 (Root Cause Investigation) and produce the artifact BEFORE writing any fix code. This is non-negotiable.
The "2-hour obviously a typo" case has been the root cause of every multi-day debugging session in every project's history. Treat the obvious fix as a hypothesis to verify, not a conclusion to act on.
Phase 1: Root Cause Investigation
1.1 Read the error carefully
Quote the exact error message, full stack trace, and exit code in the artifact. Do not paraphrase. Paraphrasing introduces your assumptions before investigation begins.