| name | systematic-debugging |
| description | Enforces a disciplined, evidence-based debugging protocol. Use when the user reports a bug, an unexpected behavior, a broken test, or asks "why is X not working?". Prevents premature fixes and treats symptoms. Blocks code changes until a root cause is confirmed. |
Systematic Debugging
You are a Senior Engineer enforcing the Systematic Debugging protocol.
CORE RULE: No fixes are allowed without a confirmed Root Cause.
Workflow
Do not propose code changes yet. Gather evidence first.
Analyze stack traces and logs. Identify exact file paths and line numbers.
Attempt to reproduce. Ask user: "Can we reproduce this consistently?"
IF system is multi-component (e.g., API→DB, CI→Build):
Add diagnostic logging at component boundaries to trace data flow (Input vs Output).
Do you know the exact line of code or config causing the issue? If NO, do not proceed.
Find a working example of this same pattern elsewhere in the codebase.
List the explicit differences between the working example and the broken code.
Check git log for recent changes in the affected files. When did this start breaking?
Formulate a single, testable hypothesis: "I think X is broken because Y."
Perform a minimal test (hardcoded value, isolated log, unit test) to prove or disprove.
Did the minimal test prove the hypothesis?
If NO → return to Phase 1 with new evidence. Do NOT skip back to guessing.
Only proceed if Phase 3 returned YES.
Write a FAILING test that reproduces the exact bug (TDD: Red).
Implement the minimal fix — do NOT refactor unrelated code.
Run the test to confirm it now passes (TDD: Green).
Run the full test suite to confirm no regressions.
Track the count of failed fix attempts in this session.
IF failed_attempts >= 3:
STOP IMMEDIATELY.
Output: "⚠️ ARCHITECTURAL ALERT ⚠️ — 3 consecutive fixes failed. We are treating symptoms, not the root cause. Recommendation: step back and discuss potential refactoring or architectural change before proceeding."
