systematic-debugging
Use for bugs/test failures. Reproduce, isolate root cause, fix, and validate with evidence.
When & Why to Use This Skill
This Claude skill provides a systematic framework for software debugging and troubleshooting. It automates the process of reproducing issues, isolating root causes through evidence-based analysis, and validating fixes with rigorous testing to ensure long-term code stability and prevent regressions.
Use Cases
- Scenario 1: Troubleshooting failed unit or integration tests by capturing environment states and creating minimal reproduction cases to isolate the failure.
- Scenario 2: Identifying the source of logic errors or production crashes by narrowing the code scope and testing falsifiable hypotheses based on log evidence.
- Scenario 3: Implementing robust bug fixes with evidence-based validation and adding guardrails like assertions or targeted tests to prevent future regressions.
| name | systematic-debugging |
|---|---|
| description | Use for bugs/test failures. Reproduce, isolate root cause, fix, and validate with evidence. |
Workflow
- Reproduce the issue reliably (capture exact commands, inputs, and environment).
- Collect evidence (logs, stack traces, failing tests, minimal repro).
- Narrow scope (bisect or localize to the smallest function/module).
- Form a hypothesis (one likely root cause) and a test to falsify it.
- Apply the smallest fix that addresses the root cause.
- Validate (re-run the repro; run the tightest relevant tests; watch for regressions).
- Add a guardrail if appropriate (assertion, validation, or targeted test).
Output expectations
- State: repro steps, hypothesis, and the verification you ran.
- Prefer minimal diffs over broad refactors.