Skip to content

claude-world/director-mode-lite / skills/debugger

debugger

Unverified

Systematic debugging method: 5-step root-cause analysis (capture, isolate, hypothesize, investigate, fix & verify) plus common bug-pattern reference. Use when errors, exceptions, test failures, or unexpected behavior appear. Loaded automatically by the debugger agent.

Debugger Skill

Director Mode Lite - Debugging Specialist


5-Step Root-Cause Method

1. CAPTURE      → Collect the full error, reproduce, define expected vs actual
2. ISOLATE      → Narrow to the smallest failing case
3. HYPOTHESIZE  → List and rank likely causes
4. INVESTIGATE  → Test hypotheses, inspect state
5. FIX & VERIFY → Apply the minimal fix, confirm, prevent recurrence

Step 1: Capture

  • Collect the complete error message and stack trace
  • Can reproduce the issue with clear steps
  • Identify the input that triggered the error
  • Know expected vs actual behavior

Step 2: Isolate

  • Identify the failure location from the stack trace
  • Which file(s) and function(s) are involved?
  • When did it start? (git bisect, git log)
  • Narrow down to the smallest reproducible case

Step 3: Hypothesize

  • List possible causes based on evidence
  • Rank hypotheses by likelihood
  • Design a test to confirm or eliminate each

Step 4: Investigate

  • Analyze error messages and logs carefully
  • Add strategic debug logging; inspect variable state at key points
  • Check for: null/undefined values, type mismatches, race conditions, resource exhaustion, external service failures

Common Bug Patterns

PatternSignsCommon Fix
Null/UndefinedCannot read property of undefinedAdd null checks / optional chaining
Off-by-oneLoop runs one too many/few timesCheck loop bounds
Race conditionIntermittent failuresAdd synchronization
Type coercion"1" + 1 = "11"Explicit type conversion
Async issuesPromise { <pending> }Await/handle promises

By language and domain:

  • JavaScript/TypeScript: undefined is not a function (binding), Cannot read property of null (optional chaining), promise rejections (async/await handling), type errors (strict mode)
  • Python: AttributeError (init/typos), TypeError (type validation), ImportError (paths, circular imports), KeyError (dict defaults)
  • Database: connection timeouts (pool exhaustion), constraint violations (validation, foreign keys), deadlocks (transaction ordering)
  • API/Network: 4xx (request validation, auth), 5xx (server-side, resource limits), timeouts (network, long-running queries)

Investigation Tools

# Search for error message
grep -r "error message" src/

# Find recent changes
git log --oneline -20
git diff HEAD~5

# Check specific function
grep -r "functionName" src/

Step 5: Fix & Verify

Apply the solution:

  • Make the minimal change; don't refactor while fixing; one fix per commit

Confirm the fix:

  • Original issue is resolved
  • No new issues introduced
  • Tests pass; add a test to prevent recurrence
  • Manual verification done

Output Format

## Debug Report

### Issue
[Description of the bug]

### Reproduction Steps
1. Step one
2. Step two
3. Observe error

### Root Cause
[Explanation of why this happens]

### Location
- **File**: `src/utils/parser.ts`
- **Line**: 45-52
- **Function**: `parseInput()`

### Fix Applied
[Description of the fix]

### Verification
- [x] Issue resolved
- [x] Tests pass
- [x] No regression
finishing-a-development-branchobra/superpowersUse when implementation is complete, all tests pass, and you need to decide how to integrate the workStars: 318kUpdated Claude CodeCodexUnverifiedInstall
systematic-debuggingobra/superpowersUse when encountering any bug, test failure, or unexpected behavior, before proposing fixesStars: 318kUpdated Claude CodeCodexUnverifiedInstall
test-driven-developmentobra/superpowersUse when implementing any feature or bugfix, before writing implementation codeStars: 318kUpdated Claude CodeCodexUnverifiedInstall
skill-creatoranthropics/skillsCreate new skills, modify and improve existing skills, and measure skill performance. Use when users want to create a skill from scratch, edit, or optimize an existing skill, run evals to test a skill, benchmark skill performance with variance analysis, or optimize a skill's description for better triggering accuracy.Stars: 196kUpdated Claude CodeCodexVerifiedInstall