← Back to skills

Development Process

Systematic Debugging

Enforces a structured debugging workflow: reproduce, hypothesize, verify, fix root cause, and audit similar code paths.

Last reviewed Mar 2, 2026

Install

Create this file in your project:

.claude/skills/systematic-debugging/SKILL.md
--- name: systematic-debugging description: Use this skill when investigating bugs, unexpected behavior, test failures, or error reports. Enforces structured root-cause analysis. --- # Systematic Debugging ## When to Use - A bug report or error is filed - Tests are failing unexpectedly - Behavior differs from what is expected - A user reports unexpected output or crashes ## Process 1. **Reproduce** -- Create a reliable reproduction of the bug. Write down the exact steps, inputs, and environment. If you cannot reproduce it, gather more information before proceeding. 2. **Hypothesize** -- Based on the reproduction, form a specific hypothesis about the root cause. State it explicitly: "I believe X is happening because Y." 3. **Verify** -- Gather evidence to confirm or reject the hypothesis. Read the relevant code, add logging, check state at each step. Do not skip to fixing. 4. **Fix root cause** -- Implement a fix that addresses the root cause, not just the symptom. Write a test that reproduces the original bug and passes with the fix. 5. **Verify fix** -- Run the reproducing test and the full test suite. Confirm the fix works and nothing else broke. 6. **Audit** -- Search the codebase for similar patterns that might have the same bug. Fix those too. ## Rules - Never guess at fixes. Always reproduce the bug first. - One hypothesis at a time. Exhaust the most likely cause before trying alternatives. - Do not apply shotgun fixes (changing multiple things hoping one works). - After fixing, always audit similar code paths for the same failure pattern. - Write a regression test for every bug you fix. - If the bug is environment-specific, document the environment requirements.

What this skill does

Systematic Debugging replaces ad-hoc troubleshooting with a repeatable scientific method. Instead of making random changes and hoping the bug disappears, this skill forces the agent through a disciplined process: reproduce, hypothesize, gather evidence, fix the root cause, and then audit for similar issues elsewhere.

The audit step is what separates good debugging from great debugging. Most bugs are not unique -- they reflect a pattern or misunderstanding that likely exists in other parts of the codebase. By requiring the agent to search for similar code after fixing the immediate issue, this skill prevents the same class of bug from recurring.

This approach is particularly effective for AI agents because it prevents the common failure mode of "shotgun debugging" -- making multiple speculative changes at once, which makes it impossible to know what actually fixed the problem (or if it was truly fixed at all).

Example workflow

A user reports that the search feature returns no results for queries with special characters. The agent will:

  1. Reproduce: Try searching for "C++ tutorial" and confirm empty results.
  2. Hypothesize: "The + characters are being URL-encoded incorrectly, causing the API query to fail."
  3. Verify: Read the search handler code, check how query params are encoded, add a log to see the actual API query being sent.
  4. Fix: Properly encode special characters before passing to the search API. Write a test for C++ queries.
  5. Verify: Run the test, run the full suite.
  6. Audit: Check all other places where user input is passed to APIs -- find and fix two more similar encoding issues.

Tips

  • If you cannot reproduce a bug, the next step is always "gather more information," not "try a fix"
  • Keep a mental model of what the code should do at each step, then compare with what it actually does
  • Time-box hypothesis verification -- if you can't confirm or reject within a few minutes, move to the next hypothesis
  • The audit step often finds more bugs than the original report

Best with tools

    Related MCP servers

    • No linked MCP servers yet.

    Related skills

    Brainstorming

    Collaborative idea-to-design exploration that asks clarifying questions, proposes approaches with tradeoffs, and iterates toward a design.

    Executing Plans

    Execute implementation plans task-by-task with verification checkpoints, sequential ordering, and frequent commits.

    Test-Driven Development

    Enforces the red-green-refactor cycle so every feature starts with a failing test before any implementation code is written.