| name | systematic-debugging |
| description | Use when encountering a bug, test failure, unexpected behavior, intermittent result, or error. |
Systematic Debugging
Overview
Announce: "I'm using the systematic-debugging skill to diagnose this issue."
Find the root cause before changing production behavior. A fast, deterministic, red-capable reproduction is the primary debugging tool.
When to Use
Use for every defect or unexplained failure, including flaky, environment-specific, multi-component, and performance-dependent symptoms.
- Start with Investigation and Hypotheses. It covers reproduction, boundary tracing, evidence, and falsifiable hypotheses.
- After evidence confirms a cause, load Fix and Regression before implementing the failing test and root-cause fix.
- Load Advanced Techniques only for regression localization, deep upstream tracing, recurring defect classes, async waits, or 3+ unsuccessful fix attempts.
Non-Negotiable Rule
DO NOT attempt fixes until Phase 1 establishes a reproducible symptom and evidence about where it originates.
Core loop:
- Reproduce the exact symptom with one agent-runnable command or structured HITL check.
- Read the complete error and inspect recent changes.
- Trace inputs and outputs until correct data becomes incorrect.
- Rank 3-5 hypotheses; each must make a falsifiable prediction.
- Test one variable at a time. If the top three fail, revisit assumptions.
- Write a failing test, implement the smallest root-cause fix, and prove RED-GREEN regression behavior.
- Remove probes, rerun the original reproduction and relevant suite, then use
verification-before-completion.
If reproduction is impossible, gather more data and report uncertainty. Never guess-fix.
Red Flags
| Thought | Required response |
|---|
| "Let me try this quick fix" | Return to reproduction and boundary evidence. |
| "I know the cause" | State and test its prediction. |
| "I cannot reproduce it, but..." | Instrument or collect data; do not patch. |
| "A try/catch will handle it" | Explain and fix the originating invalid state. |
| "Another tweak might work" after repeated attempts | Stop after 3+ attempts and question architecture. |
Integration
executing-plans routes implementation failures here.test-driven-development governs the regression cycle.verification-before-completion gates the final fix claim.architecture-enforcement helps when no clean test seam exists.knowledge-compounding captures the confirmed cause and reusable solution.
