debug

sbusso's avatarfrom sbusso

Expert debugging methodology. Triggers on debug, investigate, fix bug, troubleshoot.

⭐2stars🔀1forks📁View on GitHub🕐Updated Dec 10, 2025
[Debugging]

When & Why to Use This Skill

This Claude skill implements a rigorous, expert-level debugging methodology designed to systematically identify, analyze, and resolve software defects. By following a structured three-phase approach—Evidence Gathering, Root Cause Analysis, and Solution Verification—it ensures that bugs are not just patched but fully understood and permanently fixed, preventing regressions and improving overall code quality through a 'verify, don't assume' philosophy.

Use Cases

  • Investigating complex runtime errors or cryptic stack traces by systematically gathering evidence and analyzing recent git history.
  • Performing deep root cause analysis to move beyond surface-level symptoms and identify the actual underlying logic flaws in a codebase.
  • Developing and verifying minimal, effective code fixes that are rigorously tested against original reproduction steps to ensure long-term stability.
namedebug
descriptionExpert debugging methodology. Triggers on debug, investigate, fix bug, troubleshoot.

Debug Like an Expert

Core principle: VERIFY, DON'T ASSUME. Code you wrote deserves extra skepticism.

Phase 1: EVIDENCE GATHERING

  • Document exact error (full message, stack trace)
  • Identify affected components
  • Check recent changes (git diff, git log)
  • Research error via context7 MCP if needed

Output: Evidence summary Gate: Have reproducible steps before proceeding

Phase 2: ROOT CAUSE ANALYSIS

  • Form 2-3 testable hypotheses
  • Test ONE variable at a time
  • Read complete files, not snippets
  • Chase dependencies to their source

Output: Identified root cause with evidence Gate: Can explain WHY the bug occurs

Phase 3: SOLUTION

  • Implement minimal fix
  • Verify fix addresses root cause (not symptoms)
  • Test original reproduction steps
  • Check for regressions

Output: Working fix with verification

Rules

  • No fixes without explaining WHY they work
  • Never assume - verify every assumption
  • Test one change at a time
  • Would this fix survive code review?