arogyareddy 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.