debug-issues

name	debug-issues
description	Debug bugs and errors using intel-first approach with systematic root cause analysis. Use proactively when errors occur, tests fail, or unexpected behavior appears. MUST trace from symptom to root cause with CoD^Σ reasoning.

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:

1. Error Message:

   TypeError: Cannot read property 'discount' of undefined
   at calculateTotal (src/pricing/calculator.ts:67)
   at processCheckout (src/checkout/checkout.ts:123)
   

2. Reproduction Steps:

   1. Add items to cart
   2. Apply discount code "SAVE20"
   3. Click "Checkout"
   4. ERROR: 500 response
   

3. 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:

1. React Infinite Re-render - useEffect dependency on mutated value
2. N+1 Query Problem - Database queries inside loops
3. 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