/systematic-debugging

name: systematic-debugging
description: Debugging framework that finds root causes before proposing fixes. Use when investigating bugs, errors, unexpected behavior, failed tests, or when previous fixes haven't worked.

If the current repo has its own rules/skills covering this topic (check .claude/rules/ and repo CLAUDE.md), those take precedence — apply this skill only where they're silent.

Systematic Debugging

**If 3+ fixes have failed:** Stop fixing symptoms. Question the architecture. The bug may be a design problem, not a code problem.

**For multi-component systems:** Add diagnostic logging at each component boundary before proposing fixes. See [references/debugging-techniques.md](references/debugging-techniques.md) for instrumentation patterns (binary search, git bisect, minimal reproduction, strategic logging, differential analysis).

**For large or multi-file log investigations:** Delegate to the `@ce:log-reader` agent for efficient analysis. Not needed for a single short stack trace.

Reporting Format

## Root Cause
[1-3 sentences explaining underlying issue]
Located in: `file.ts:123`

## What Was Wrong
[Specific problem - mutation, race condition, missing validation, etc. 1-3 sentences]

## The Fix
[Changes made and why they address root cause. 1-3 sentences]

## Verification
[How the fix was confirmed - e.g. reran the failing test, reproduced and retested manually]