systematic-debugging

rozwer's avatarfrom rozwer

Use for bugs/test failures. Reproduce, isolate root cause, fix, and validate with evidence.

⭐0stars🔀0forks📁View on GitHub🕐Updated Dec 29, 2025⬇️1downloads

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.
namesystematic-debugging
descriptionUse for bugs/test failures. Reproduce, isolate root cause, fix, and validate with evidence.

Workflow

  1. Reproduce the issue reliably (capture exact commands, inputs, and environment).
  2. Collect evidence (logs, stack traces, failing tests, minimal repro).
  3. Narrow scope (bisect or localize to the smallest function/module).
  4. Form a hypothesis (one likely root cause) and a test to falsify it.
  5. Apply the smallest fix that addresses the root cause.
  6. Validate (re-run the repro; run the tightest relevant tests; watch for regressions).
  7. 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.