systematic-debugging

maslennikov-ig's avatarfrom maslennikov-ig

Use when encountering any bug, test failure, or unexpected behavior, before proposing fixes

⭐1stars🔀0forks📁View on GitHub🕐Updated Jan 9, 2026
[Debugging]

When & Why to Use This Skill

The Systematic Debugging skill provides a rigorous, four-phase framework designed to identify and resolve software defects by prioritizing root cause analysis over superficial fixes. By guiding Claude through structured investigation, pattern analysis, and hypothesis testing, it ensures that bug resolution is evidence-based, preventing the common pitfall of 'guess-and-check' programming and ensuring long-term code stability.

Use Cases

  • Root Cause Analysis: Investigating complex stack traces and error logs to find the exact source of a failure before writing any code.
  • Test Failure Resolution: Systematically addressing failing unit or integration tests by reproducing the issue and creating a minimal failing test case.
  • Regression Analysis: Comparing current failing code against previous working versions or reference implementations to identify breaking changes.
  • Multi-Component Troubleshooting: Tracing data flow across microservices or complex system boundaries to locate where a process breaks down.
  • Hypothesis-Driven Fixing: Testing specific theories about a bug with minimal changes to verify the root cause before implementing a final solution.
namesystematic-debugging
descriptionUse when encountering any bug, test failure, or unexpected behavior, before proposing fixes

Systematic Debugging

Core principle: ALWAYS find root cause before attempting fixes.

NO FIXES WITHOUT ROOT CAUSE INVESTIGATION FIRST

The Four Phases

Phase 1: Root Cause Investigation

BEFORE attempting ANY fix:

  1. Read Error Messages Carefully - Stack traces, line numbers, error codes
  2. Reproduce Consistently - Exact steps, every time?
  3. Check Recent Changes - Git diff, new deps, config changes
  4. Gather Evidence in Multi-Component Systems - Log data at each component boundary, run once, analyze WHERE it breaks

Phase 2: Pattern Analysis

  1. Find Working Examples - Similar working code in same codebase
  2. Compare Against References - Read reference implementation COMPLETELY
  3. Identify Differences - List every difference, however small

Phase 3: Hypothesis and Testing

  1. Form Single Hypothesis - "I think X is the root cause because Y"
  2. Test Minimally - SMALLEST possible change, one variable at a time
  3. Verify Before Continuing - Didn't work? Form NEW hypothesis, don't stack fixes

Phase 4: Implementation

  1. Create Failing Test Case - MUST have before fixing
  2. Implement Single Fix - ONE change at a time, no "while I'm here" improvements
  3. Verify Fix - Test passes? No other tests broken?
  4. If 3+ Fixes Failed - STOP. Question the architecture, discuss with human partner

Red Flags - STOP and Return to Phase 1

  • "Quick fix for now, investigate later"
  • "Just try changing X and see if it works"
  • "I don't fully understand but this might work"
  • Proposing solutions before tracing data flow
  • Each fix reveals new problem in different place

Quick Reference

Phase Key Activity Success Criteria
1. Root Cause Read errors, reproduce, check changes Understand WHAT and WHY
2. Pattern Find working examples, compare Identify differences
3. Hypothesis Form theory, test minimally Confirmed or new hypothesis
4. Implementation Create test, fix, verify Bug resolved, tests pass