Debugging Skill
Overview
This skill performs systematic bug diagnosis using intelligence-first approach to trace from symptom to root cause with complete CoD^Σ reasoning chain.
Core principle: Capture symptom → Parse error → Intel trace → Root cause → Propose fix
Announce at start: "I'm using the debug-issues skill to diagnose this problem."
Quick Reference
| Phase | Key Activities | Output |
|---|---|---|
| 1. Capture Symptom | Reproduction steps, error message, environment | Symptom description |
| 2. Parse Error | Extract error type, file:line, stack trace | Parsed error object |
| 3. Intel Trace | project-intel.mjs queries from error to cause | Intel evidence chain |
| 4. Root Cause | Identify specific file:line with CoD^Σ trace | Root cause |
| 5. Report | Generate bug report with fix proposal | bug-report.md |
Templates You Will Use
- @.claude/templates/bug-report.md - Complete bug report with fix (Phase 5)
- @.claude/templates/mcp-query.md - For verifying library behavior (Phase 4)
Intelligence Tool Guide
- @.claude/shared-imports/project-intel-mjs-guide.md - For systematic intel queries
The Process
Copy this checklist to track progress:
Debugging Progress:
- [ ] Phase 1: Symptom Captured (reproduction steps documented)
- [ ] Phase 2: Error Parsed (file:line extracted)
- [ ] Phase 3: Intel Trace Complete (queries executed)
- [ ] Phase 4: Root Cause Identified (specific file:line)
- [ ] Phase 5: Bug Report Generated (with fix proposal)
Phase 1: Capture Symptom
Document the complete symptom:
-
Error Message:
TypeError: Cannot read property 'discount' of undefined at calculateTotal (src/pricing/calculator.ts:67) at processCheckout (src/checkout/checkout.ts:123) -
Reproduction Steps:
``` - Add items to cart
- Apply discount code "SAVE20"
- Click "Checkout"
-
ERROR: 500 response
``` -
Frequency & Environment:
- Frequency: 15% of checkout attempts - Environment: Production - User impact: High (blocks checkout)
Enforcement:
- [ ] Complete error message captured
- [ ] Reproduction steps documented
- [ ] Frequency and environment noted
Phase 2: Parse Error
Extract structured information from error:
Parse Stack Trace
ERROR: TypeError: Cannot read property 'discount' of undefined
at calculateTotal (src/pricing/calculator.ts:67) ← ROOT ERROR
at processCheckout (src/checkout/checkout.ts:123)
at POST /api/checkout (src/api/routes.ts:45)
Parsed:
{
error_type: "TypeError",
message: "Cannot read property 'discount' of undefined",
root_location: "src/pricing/calculator.ts:67",
root_function: "calculateTotal",
call_chain: [
"src/api/routes.ts:45",
"src/checkout/checkout.ts:123",
"src/pricing/calculator.ts:67"
]
}
Identify Entry Point
Entry point: src/pricing/calculator.ts:67
Function: calculateTotal
Issue: Accessing .discount on undefined object
Enforcement:
- [ ] Error type identified
- [ ] Root file:line extracted
- [ ] Function name identified
- [ ] Call chain documented
Phase 3: Intel Trace
See: @.claude/skills/debug-issues/workflows/intel-trace.md
Summary:
Systematic 4-query workflow using project-intel.mjs to trace from error to root cause.
Query Workflow:
1. Locate Function: Find file containing the error-causing function
2. Analyze Symbols: Get exact line numbers for functions
3. Trace Dependencies: Check what the function imports
4. Check Dependency: Analyze suspicious imports for return types
Token Efficiency:
- Intel queries: ~350 tokens
- Targeted reads: ~400 tokens
- Total: ~750 tokens vs 8600 (91% savings)
Phase 4: Root Cause Analysis
See: @.claude/skills/debug-issues/workflows/root-cause-analysis.md
Summary:
Use targeted reads (ONLY lines identified by intel) to identify root cause with complete CoD^Σ trace.
CoD^Σ Trace Pattern:
Step 1: → ParseError (from Phase 2)
Step 2: ⇄ IntelQuery (locate function)
Step 3: ⇄ IntelQuery (analyze symbols)
Step 4: → TargetedRead (error location)
Step 5: ⇄ IntelQuery (check dependency)
Step 6: → TargetedRead (dependency function)
Step 7: ⊕ MCPVerify (best practices)
Step 8: ∘ Conclusion (root cause + fix)
Requirements:
- Specific file:line for root cause
- Complete evidence chain
- MCP verification for library behavior
- Token efficiency analysis
Phase 5: Bug Report Generation
See: @.claude/skills/debug-issues/workflows/bug-report-generation.md
Summary:
Generate comprehensive bug report using @.claude/templates/bug-report.md with:
Required Sections:
1. Symptom - From Phase 1
2. CoD^Σ Trace - From Phase 4
3. Root Cause - Specific file:line + explanation
4. Fix Specification - Exact code changes (before/after)
5. Verification - Test plan + acceptance criteria
File Naming: YYYYMMDD-HHMM-bug-<id>.md
Common Error Patterns
See: @.claude/skills/debug-issues/examples/error-patterns.md
Summary:
Three frequently encountered patterns with systematic debugging approaches:
- React Infinite Re-render - useEffect dependency on mutated value
- N+1 Query Problem - Database queries inside loops
- Memory Leak - Missing cleanup in useEffect
Each pattern includes:
- Symptom identification
- Step-by-step debugging process
- Common root causes
- Fix approaches with code examples
- Verification steps
Enforcement Rules
See: @.claude/skills/debug-issues/references/debugging-rules.md
Summary:
Three mandatory rules for all bug diagnosis:
Rule 1: Complete CoD^Σ Trace
- Every step must have evidence source
- File:line references required
- MCP queries documented
- Conclusion follows logically
Rule 2: Intel Before Reading
- ALWAYS query project-intel.mjs first
- Use targeted reads (sed -n 'X,Yp')
- Document token savings
- Never read full files
Rule 3: Fix with Verification
- Propose specific code changes
- Include test plan
- Define acceptance criteria
- Verify fix addresses root cause
Common Pitfalls:
- Assumptions without MCP verification
- Skipping intel queries (91% token waste)
- Incomplete reproduction steps
- No fix proposal
When to Use This Skill
Use debug-issues when:
- User reports an error or bug
- Tests are failing
- Unexpected behavior occurs
- Performance is degraded
- Memory issues detected
Don't use when:
- User wants general code analysis (use analyze-code skill)
- User wants to plan implementation (use create-plan skill)
- No specific error (use analyze-code for investigation)
Related Skills & Commands
- Analyze-code skill - For general code analysis (not bug-specific)
- Implement-and-verify skill - For implementing the fix after debugging
- /bug command - User-invoked debugging (can invoke this skill)
Success Metrics
Accuracy:
- Root cause identified: 95%+
- Fix proposal validated: 100%
Efficiency:
- Token usage: 80%+ savings vs direct reading
- Time to diagnosis: 5-15 minutes
Completeness:
- CoD^Σ trace: 100% complete
- MCP verification: 100% for library issues
Prerequisites
Before using this skill:
- ✅ Error or bug has been reported/detected
- ✅ Error message, logs, or reproduction steps available
- ✅ project-intel.mjs exists and is executable
- ✅ PROJECT_INDEX.json exists (run /index if missing)
- ⚠️ Optional: MCP tools configured (Ref for library behavior verification)
- ⚠️ Optional: Test framework set up (for verification tests)
Dependencies
Depends On:
- None (this skill is standalone and can be used at any point)
Integrates With:
- analyze-code skill - Use before this skill for general code understanding
- implement-and-verify skill - Use after this skill to implement the fix
- create-implementation-plan skill - Use after this skill if fix requires multiple changes
Tool Dependencies:
- project-intel.mjs (intelligence queries)
- MCP Ref tool (library documentation, optional)
- Read, Grep tools (targeted code reading)
- Bash tool (running sed for targeted reads, running tests)
Next Steps
After debugging completes, typical progression:
For simple fixes (1 file, <10 lines):
debug-issues (identifies root cause + proposes fix)
↓
User approves fix OR implement-and-verify skill implements it
↓
Run tests to verify fix works
For complex fixes (multiple files, refactoring needed):
debug-issues (identifies root cause)
↓
create-implementation-plan (plan multi-file fix)
↓
generate-tasks (break down fix tasks)
↓
implement-and-verify (implement fix with TDD)
For blocked/requires research:
debug-issues (unable to identify root cause)
↓
analyze-code skill (deeper investigation)
↓
MCP queries (verify library behavior)
↓
debug-issues skill (re-run with additional context)
User Action Required:
- Provide reproduction steps if not already known
- Approve fix proposal before implementation
- Run verification tests after fix applied
Outputs Created:
- YYYYMMDD-HHMM-bug-<id>.md - Complete bug report with CoD^Σ trace and fix
- Updated code (if implementing fix immediately)
- Test files (if verification tests created)
Commands:
- /implement plan.md - If fix requires planned implementation
- /verify plan.md - If fix needs formal verification
Failure Modes
Common Failures & Solutions
1. PROJECT_INDEX.json missing or stale
- Symptom: Intel queries fail or return outdated results
- Solution: Run /index command to regenerate index
- Prevention: Hook auto-generates index on file changes
2. Incomplete error information
- Symptom: No stack trace, vague error message, can't reproduce
- Solution: Ask user for complete error log, reproduction steps, environment details
- Requirement: Need at least error message + approximate location to start
3. Reading full files instead of intel-first
- Symptom: Token usage high (>5K for simple bug), slow diagnosis
- Solution: ALWAYS query project-intel.mjs before reading any files
- Pattern: Search → Symbols → Dependencies → Targeted Read (never full file read)
4. No CoD^Σ trace documented
- Symptom: Bug report lacks reasoning chain, can't verify logic
- Solution: Document every step from symptom to root cause
- Enforcement: Phase 4 requires complete CoD^Σ trace in bug report
5. Proposing fix without verification plan
- Symptom: Fix suggested but no way to test it
- Solution: Always include test plan with acceptance criteria
- Pattern: "Test with X (should Y), Test with Z (should not error)"
6. Assumptions without MCP verification
- Symptom: Assuming library behavior, fix doesn't work
- Solution: Use Ref MCP to verify library behavior before proposing fix
- Example: "React useEffect cleanup" → verify in React docs before proposing solution
7. Jumping to conclusions without intel trace
- Symptom: Guessing root cause, diagnosis wrong
- Solution: Systematically trace from error location through dependencies
- Enforcement: Phases 2-3 must execute before identifying root cause
8. Symptom captured incompletely
- Symptom: Missing frequency, environment, user impact details
- Solution: Phase 1 checklist enforces complete symptom capture
- Components: Error + Reproduction Steps + Frequency + Environment + Impact
9. Not using sed for targeted reads
- Symptom: Reading entire files when only need specific lines
- Solution: Use sed -n 'X,Yp' file after intel identifies line range
- Benefit: Read 10-20 lines instead of 1000+ lines (99% token savings)
10. Parallel investigation instead of systematic
- Symptom: Trying multiple approaches simultaneously, getting confused
- Solution: Follow phase order: Symptom → Parse → Intel → Root Cause → Report
- Enforcement: Copy progress checklist and mark phases sequentially
Related Skills & Commands
Direct Integration:
- analyze-code skill - Use before this skill for general understanding, or when debugging blocks
- implement-and-verify skill - Use after this skill to implement fix with TDD
- create-implementation-plan skill - Use after this skill if fix is complex
- /bug command - User-facing command that invokes this skill
- code-analyzer subagent - Subagent that can route to this skill
Workflow Context:
- Position: Troubleshooting (parallel to main workflow, invoked when errors occur)
- Triggers: Error reports, test failures, unexpected behavior
- Output: bug-report.md with root cause, CoD^Σ trace, and fix proposal
Quality Gates:
- Intel-First: MUST query project-intel.mjs before reading files (Article I)
- Evidence-Based: Complete CoD^Σ trace required (Article II)
- Verification Plan: Fix must have testable acceptance criteria (Article III)
Common Entry Points:
1. User reports bug → debug-issues skill
2. Tests fail during /implement → implement-and-verify invokes debug-issues skill
3. analyze-code identifies issue → routes to debug-issues for diagnosis
Common Exit Points:
1. Simple fix → Implement immediately
2. Complex fix → create-implementation-plan skill
3. Cannot reproduce → Request more info from user
4. Requires research → analyze-code skill for deeper investigation
Version
Version: 1.1.0
Last Updated: 2025-10-23
Owner: Claude Code Intelligence Toolkit
Change Log:
- v1.1.0 (2025-10-23): Refactored to progressive disclosure pattern (<500 lines)
- v1.0.0 (2025-10-22): Initial version with systematic debugging workflow
