debugger
npx machina-cli add skill claude-world/director-mode-lite/debugger --openclawFiles (1)
SKILL.md
2.3 KB
Debugger Skill
Director Mode Lite - Debugging Specialist
Role
You are a debugging specialist focused on systematic root cause analysis and problem resolution.
Debugging Methodology
5-Step Debug Process
1. REPRODUCE → Confirm the bug exists
2. ISOLATE → Narrow down the scope
3. IDENTIFY → Find the root cause
4. FIX → Apply the solution
5. VERIFY → Confirm the fix works
Step 1: Reproduce
Before debugging, confirm:
- Can reproduce the issue
- Have clear steps to reproduce
- Know expected vs actual behavior
- Have relevant error messages/logs
Step 2: Isolate
Narrow down the problem:
- Which file(s) are involved?
- Which function(s) are involved?
- When did it start? (git bisect)
- What changed recently?
Step 3: Identify
Find the root cause:
Common Bug Patterns
| Pattern | Signs | Common Fix |
|---|---|---|
| Null/Undefined | Cannot read property of undefined | Add null checks |
| Off-by-one | Loop runs one too many/few times | Check loop bounds |
| Race condition | Intermittent failures | Add synchronization |
| Type coercion | "1" + 1 = "11" | Explicit type conversion |
| Async issues | Promise { <pending> } | Await/handle promises |
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 4: Fix
Apply the solution:
- Make minimal changes
- Don't refactor while fixing
- One fix per commit
Step 5: Verify
Confirm the fix:
- Original issue is resolved
- No new issues introduced
- Tests pass
- 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
Source
git clone https://github.com/claude-world/director-mode-lite/blob/main/skills/debugger/SKILL.mdView on GitHub Overview
Debugger helps you perform systematic root cause analysis to resolve problems. It follows a disciplined 5-step process—reproduce, isolate, identify, fix, and verify—using concrete patterns and investigation tools to deliver reliable fixes.
How This Skill Works
Begins by reproducing the bug to confirm it exists, then isolates the scope to narrow down the culprit. It identifies the root cause using common bug patterns and investigation tools (grep, git log, git diff), applies a minimal fix, and finally verifies that the issue is resolved without introducing regressions.
When to Use It
- When a bug is reported with unclear root cause and requires reproducible steps to confirm the issue.
- When failures are intermittent and may involve race conditions or asynchronous issues.
- When error messages point to common patterns like null/undefined, off-by-one, type coercion, or async problems.
- When a fix must be minimal and well-scoped, with a clear verification plan.
- When reviewing code after a deployment to isolate the faulty area and confirm the fix.
Quick Start
- Step 1: REPRODUCE — Confirm the bug exists with clear steps and compare expected vs actual behavior.
- Step 2: ISOLATE — Narrow down the responsible file(s) and function(s) using targeted searches and git history.
- Step 3: IDENTIFY/FIX/VERIFY — Find the root cause, apply a minimal fix, and verify with tests and manual checks.
Best Practices
- Reproduce the issue with clear, repeatable steps and document expected vs actual behavior.
- Isolate the problem using focused file/function analysis and version history (git bisect is helpful).
- Identify the root cause by consulting common bug patterns and verification tools.
- Apply a minimal, single-change fix; avoid large refactors during debugging.
- Verify thoroughly with automated tests, logs, and manual checks to ensure no regressions.
Example Use Cases
- Null/Undefined access in a parsing function fixed by adding null checks.
- Race condition in parallel data fetch resolved by introducing synchronization.
- Off-by-one error in a loop corrected by reviewing loop bounds.
- Async issue where a Promise remained pending resolved by awaiting the result or proper then chaining.
- Type coercion bug in input handling fixed with explicit type conversion.
Frequently Asked Questions
Add this skill to your agents
