| name | systematic-debugging |
| description | Reproduce-first debugging protocol — never claim fixed without reproducing the bug |
| allowed-tools | ["Read","Grep","Glob","Bash","Write","Edit"] |
| auto-activate | bug-fixing (all levels) |
| required-before | Any bug fix implementation |
| version | 2.0.0 |
| when | [{"task_type":"bug","risk_level":["low","medium","high","critical"]},{"user_mentions":["bug","error","fix","broken","not working","fails"]}] |
| load_when | ["debugging_production_issue","investigating_test_failure","diagnosing_unexpected_behavior"] |
| inputs | [{"name":"bug_description","type":"string","required":true},{"name":"error_logs","type":"string","required":false},{"name":"reproduction_steps","type":"array","required":false}] |
| outputs | [{"name":"root_cause_analysis","type":"structured_report","format":"Symptom | Root cause | Evidence | Fix | Verification"},{"name":"reproduction_test","type":"string","format":"Test that fails before fix, passes after"}] |
| constraints | ["reproduce_bug_before_fixing","write_failing_test_before_implementing_fix","never_claim_fixed_without_verification_evidence"] |
Systematic Debugging — NO FIXES WITHOUT ROOT CAUSE
REGLA FUNDAMENTAL: NO BUG FIXES WITHOUT ROOT CAUSE ANALYSIS.
This skill enforces a 4-phase debugging process for any bug fix.
When to Invoke
- Task classified as
bug at any risk level
- User mentions: "bug", "error", "fix", "broken", "not working", "fails"
- Investigating a test failure or production issue
- Diagnosing unexpected behavior
- Auto-activated for bug-fixing workflows (mandatory at medium+ risk)
The 4 Phases (Mandatory)
| Phase | Goal | Reference |
|---|
| 1. Reproduce | Create a test that demonstrates the bug consistently (must fail) | references/phase-1-reproduce.md |
| 2. Root Cause | Identify the real cause via 5 Whys, stack trace, logs, diff | references/phase-2-root-cause.md |
| 3. Hypothesis | Propose fix and validate before implementing | references/phase-3-hypothesis.md |
| 4. Implementation | Implement fix + defense-in-depth + regression test | references/phase-4-implementation.md |
Each phase has a CHECKPOINT — cannot proceed to the next without completing the current.
Phase 1.4 — Multi-Component Diagnostic Instrumentation
For EACH component boundary in the suspected path:
- Log entry: what's coming in
- Log exit: what's going out
- Log config: what's the current config state
- Log state: what's the current data state
Re-run the failing scenario. Compare boundary logs across components. The bug lives where expectations diverge from reality — usually at a boundary, not within a component.
Phase 4.5 — If 3+ Fixes Failed, Question Architecture
Pattern indicating an architectural problem (not a failed hypothesis):
- Each fix reveals new shared state or coupling in a different place
- Fixes require "massive refactoring" to implement properly
- Each fix creates new symptoms elsewhere
- You're chasing the bug, not understanding it
STOP and question fundamentals:
- Is this pattern fundamentally sound for this use case?
- Are we sticking with it through sheer inertia or sunk cost?
- Should we refactor the architecture vs. continue patching symptoms?
Discuss with the user BEFORE attempting fix #4. This is NOT a failed hypothesis to retry — this is a wrong architecture to redesign.
Anti-Patterns (Red Flags)
"I Know What the Problem Is"
- WRONG: "I know it's a database issue, let me add an index"
- RIGHT: "Let me reproduce it first, then analyze root cause"
- Problem: assumptions without evidence lead to wrong fixes.
"Quick Fix First, Investigate Later"
- WRONG: "Let me wrap it in try-catch for now, we'll debug later"
- RIGHT: "No fixes until root cause identified"
- Problem: "later" never comes; bug remains hidden.
"It's Too Complex to Reproduce"
- WRONG: "The bug is intermittent, I'll just add more logging"
- RIGHT: "I'll create conditions that make it reproducible"
- Problem: can't fix what you can't reproduce.
"The Fix Looks Good"
- WRONG: "This should fix it" (without running test)
- RIGHT: "Test passes, bug confirmed fixed: [output]"
- Problem: verification-enforcement should catch this.
Need → Reference
| Need | Reference |
|---|
| How to write a reproducing test | references/phase-1-reproduce.md |
| 5 Whys, stack trace, logging techniques | references/phase-2-root-cause.md |
| Forming and validating a hypothesis | references/phase-3-hypothesis.md |
| Implementing fix with defense-in-depth | references/phase-4-implementation.md |
| Concrete examples by bug type (perf, security, logic, race) | references/examples-by-bug-type.md |
| Ralph Loop iterative debugging mode | references/ralph-loop-integration.md |
Pre-claim Checklist (before "fixed")
Phase 1: Reproduce
Phase 2: Root Cause
Phase 3: Hypothesis
Phase 4: Implementation
Summary
FOR every bug fix:
PHASE 1: Create test that reproduces bug (must fail)
PHASE 2: Identify root cause (not symptom)
PHASE 3: Form hypothesis and validate
PHASE 4: Implement + defense-in-depth + regression test
NO shortcuts. NO quick fixes. NO "I know what it is."
The most expensive bug is the one that comes back.
Auto-Activated In: All bug-fixing workflows (all risk levels)
Ralph-Ready: Yes (v2.0) — see references/ralph-loop-integration.md
Can Be Skipped: NO (mandatory for bugs medium+ risk)
Integrates With: test-driven-development, verification-enforcement, ralph-loop-wrapper
