| name | systematic-debug |
| description | 5-phase structured debugging protocol. Use when encountering any bug, test failure, unexpected behavior, production incident, or error trace. Triggers on "debug this", "why is this failing", "fix this error", "this isn't working", stack traces, error messages, or failed test output anywhere in the prompt. Always runs before proposing any fix. |
Systematic Debug Skill
Non-Negotiable Rule
Never propose a fix before completing Phase 2 (Root Cause Hypothesis).
A fix without a cause is a guess.
Guesses compound bugs — you fix the symptom, the root cause remains,
and you see the same failure class again in 3 weeks.
The 5 phases are sequential. No skipping. No shortcutting to Phase 4
because "it's obviously just an off-by-one error."
Phase 1 — Intake & Reproduction
Document exactly what is known:
- Error message or failure symptom (verbatim, not paraphrased)
- Environment: runtime, version, OS, deployment context (dev/staging/prod)
- Last change that preceded the failure (git diff, deploy timestamp, config change)
- Whether the failure is deterministic or intermittent
- Reproduction steps (exact commands or user actions to trigger it)
If reproduction steps are unknown, STOP and ask before proceeding.
A bug you cannot reproduce cannot be fixed reliably.
"It happens sometimes" is not a reproduction case.
Phase 2 — Root Cause Hypothesis
Generate 2–3 candidate root causes, ranked by likelihood.
For each candidate:
- Name the cause in one sentence
- Identify the exact code path or system state involved
- State the evidence that supports this hypothesis
- State what evidence would rule it out
Do NOT skip to the most obvious cause.
Payroll bugs often have compounding causes:
- Rounding error + timezone offset + pay period boundary
- Concurrent update + missing transaction + cache staleness
- Correct logic + wrong input assumption + missing validation
Phase 3 — Targeted Investigation
For the highest-ranked hypothesis:
- Identify exactly which file(s) and line range to inspect
- Write a targeted test or diagnostic that confirms or falsifies the hypothesis
- If the test confirms: proceed to Phase 4
- If the test falsifies: return to Phase 2, re-rank remaining hypotheses
Never read the entire codebase looking for the bug.
Name the specific location. Read only what is needed.
Token cost of unfocused exploration: high. Return: zero.
Phase 4 — Minimal Fix
Write the smallest possible change that addresses the confirmed root cause.
Rules:
- One root cause = one fix. Never bundle unrelated improvements.
- If the fix requires touching more than 3 files, the scope is likely wrong.
Stop and verify the root cause before expanding scope.
- Preserve existing behavior in all paths not related to the confirmed bug.
- Add a regression test that FAILS before the fix and PASSES after.
This test is the proof the fix is correct. Without it, the fix is a guess.
Phase 5 — Verification & Blast Radius
After applying the fix:
- Re-run the reproduction steps. Confirm the original failure is gone.
- Identify the blast radius: every caller, consumer, downstream system affected.
- Check for regressions in adjacent functionality.
- Run the full test suite if the fix touches shared utilities or models.
Close with this exact output format:
ROOT CAUSE: [One sentence — what was wrong and why]
FIX: [One sentence — what was changed]
FILES CHANGED: [List]
REGRESSION TEST: [Test file and test name]
BLAST RADIUS: [Systems checked / none affected / exceptions noted]
PREVENTED BY: [What spec gap, test gap, or review miss allowed this through]
The PREVENTED BY field feeds DECISIONS.md under DEFECT LEARNINGS.
It is required. It is how the codebase gets smarter over time.
