| name | systematic-debugging |
| description | Structured root-cause debugging protocol. Use when encountering any bug, test failure, or unexpected behavior. |
| origin | Orchestrator — earned through direct practice (see commit history) |
| source_version | 2026-04-18 |
Systematic Debugging Protocol
IRON LAW: NO FIXES WITHOUT ROOT CAUSE INVESTIGATION FIRST.
You MUST complete Phase 1 before proposing any fix. If you catch yourself wanting to "just try something" — STOP. That impulse is the problem this protocol exists to solve.
Phase 1: Root Cause Investigation (MANDATORY GATE)
Complete ALL of these before moving to Phase 2:
- Read the full error — every line of the stack trace, every warning. Don't skim.
- Reproduce reliably — run the failing command yourself. If it can't be reproduced, collect more data. Do NOT guess.
- Check recent changes —
git diff, git log --oneline -10, env changes. The bug is usually in what changed.
- Add diagnostic logging — at every component boundary: input/output/state. Run once. Find where the chain breaks.
- Backward trace (5 levels) — from the error, trace backwards through the call chain. At each level ask: "Is the input to this function correct?" Find where the bad value was introduced.
Gate check: Can you state the root cause in one sentence? If not, you're not done with Phase 1.
Phase 2: Pattern Analysis
- Find a working example of similar functionality
- Line-by-line comparison — list every difference between working and broken
- Identify hidden assumptions and implicit dependencies
Phase 3: Hypothesis & Testing
- Write down one hypothesis — be specific ("X is null because Y doesn't initialize before Z")
- Design the smallest possible test for that hypothesis
- Run the test
- If falsified → new hypothesis from scratch. Do NOT stack fixes. Do NOT combine "maybe this AND that".
Phase 4: Implementation
- Write a failing test that reproduces the bug
- Make the minimal fix — change as few lines as possible
- Run all tests — verify no regressions
- If the fix exposes a new problem in a different location → see 3-Attempt Rule below
3-Attempt Architectural Escalation
Track your fix attempts:
- Attempt 1 fails → OK, revise hypothesis, try again
- Attempt 2 fails → Slow down. Re-read Phase 1 notes. Is the root cause actually identified?
- Attempt 3 fails → STOP IMMEDIATELY. This is likely an architectural issue, not a local bug.
On the third failure, output this report to the user:
## Debugging Escalation Report
**Bug**: [description]
**Root cause hypothesis**: [your best guess]
**3 attempts tried**: [what each attempt changed and why it failed]
**Why this might be architectural**: [what pattern you're seeing]
**Recommendation**: [what the user should consider]
Do NOT attempt a 4th fix. The user decides the next step.
Rationalization Immunity
These thoughts mean you're about to violate the protocol:
| Thought | Reality |
|---|
| "I already know what's wrong" | Then Phase 1 should take 30 seconds. Do it anyway. |
| "This is a simple typo" | Typos don't need 3 attempts. If it's simple, Phase 1 is fast. |
| "Let me just try this quick fix" | Quick fixes that skip investigation cause 80% of debugging spirals. |
| "The error message is clear enough" | Read the FULL trace. The obvious line is often not the root cause. |
| "I don't need to reproduce it" | If you can't reproduce it, you can't verify the fix. |
| "I'll add the test after fixing" | That's not TDD, that's confirmation bias. Test first. |
| "This is taking too long, let me just..." | Impatience is the #1 cause of debugging spirals. Slow down. |
| "The third attempt is different enough" | Three failures = wrong mental model. Stop and escalate. |
Post-Fix Hardening
After a successful fix, add ONE layer of defense:
- A validation at the function entry point, OR
- A type check where the bad value was introduced, OR
- A test case that catches this category of bug
Goal: make this class of bug structurally impossible, not just fixed in this instance.
