Debugger Skill

This skill provides a systematic approach to debugging issues in new or existing codebases.

What it is

A structured methodology for finding and fixing bugs rather than applying random trial-and-error changes.

What it does

• •Guides reproduction of issues.
• •Implements systematic root cause analysis.
• •Encourages minimal, well-understood fixes.
• •Ensures fixes are verified and do not introduce regressions.
• •Captures findings so they can inform future work.

Why it is important

Undisciplined debugging is inefficient and risks masking symptoms without addressing root causes. A systematic approach improves understanding of the codebase and leads to durable fixes that are easier to maintain.

Process

1. •

   Reproduce

   • •Confirm that the bug exists and can be reproduced reliably.
   • •Capture exact steps, inputs, and environment details.
2. •

   Isolate

   • •Narrow down the code paths where the bug manifests.
   • •Use logging, breakpoints, or targeted tests to localize the problem.
3. •

   Hypothesize

   • •Form one or more theories about the root cause.
   • •Prefer small, testable hypotheses over broad assumptions.
4. •

   Test

   • •Design experiments or tests to confirm or refute each hypothesis.
   • •Update your understanding based on results.
5. •

   Fix

   • •Implement the minimal change that addresses the confirmed root cause.
   • •Avoid opportunistic refactors unless they are essential to the fix and approved.
6. •

   Verify

   • •Re-run reproduction steps to ensure the bug is resolved.
   • •Run existing tests and add new ones if coverage is lacking.
   • •Check for likely regressions in adjacent behavior.
7. •

   Document

   • •Record what caused the bug and why the fix works.
   • •Note any follow-up work or areas that may need deeper refactor.

This skill should be combined with the bugfix workflow and code-review skill for a complete debugging lifecycle.