Debug Issues

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

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

Use project-intel.mjs to trace from error to cause.

Query 1: Locate Function

project-intel.mjs --search "calculateTotal" --type ts --json > /tmp/debug_search.json

Result:

{
  "files": [
    "src/pricing/calculator.ts",
    "src/pricing/calculator.test.ts"
  ]
}

Query 2: Analyze Symbols

project-intel.mjs --symbols src/pricing/calculator.ts --json > /tmp/debug_symbols.json

Result:

{
  "symbols": [
    {"name": "calculateTotal", "line": 62, "type": "function"},
    {"name": "applyDiscount", "line": 89, "type": "function"},
    {"name": "getDiscount", "line": 105, "type": "function"}
  ]
}

Key Finding: calculateTotal is at line 62, error at line 67 (5 lines into function)

Query 3: Trace Dependencies

# What does calculateTotal import?
project-intel.mjs --dependencies src/pricing/calculator.ts --direction upstream --json

Result:

{
  "imports": [
    {"module": "./discountService", "symbols": ["getDiscount"]},
    {"module": "../models/Cart", "symbols": ["Cart"]},
    {"module": "../utils/currency", "symbols": ["formatPrice"]}
  ]
}

Key Finding: Imports getDiscount from discountService - likely source of undefined

Query 4: Check getDiscount Function

project-intel.mjs --symbols src/pricing/discountService.ts --json

Result:

{
  "symbols": [
    {"name": "getDiscount", "line": 12, "type": "function", "returns": "Discount | undefined"}
  ]
}

CRITICAL FINDING: getDiscount returns Discount | undefined - can be undefined!

Enforcement:

• All relevant files identified
• Symbol locations found
• Dependencies traced
• Return types checked

Phase 4: Identify Root Cause

Now read ONLY the relevant lines identified by intel:

Targeted Read 1: Error Location

sed -n '62,75p' src/pricing/calculator.ts

Code:

// Line 62
export function calculateTotal(cart: Cart, discountCode?: string): number {
  const subtotal = cart.items.reduce((sum, item) => sum + item.price * item.quantity, 0)

  // Line 67 - ERROR LINE
  const discountAmount = discountCode
    ? getDiscount(discountCode).discount * subtotal  // ← BUG: no null check
    : 0

  const total = subtotal - discountAmount
  return formatPrice(total)
}

Targeted Read 2: getDiscount Function

sed -n '12,25p' src/pricing/discountService.ts

Code:

// Line 12
export function getDiscount(code: string): Discount | undefined {
  const discount = discounts.find(d => d.code === code && d.active)
  return discount  // ← Returns undefined when code not found
}

Root Cause Analysis (CoD^Σ)

**Claim:** Error occurs because calculateTotal doesn't handle undefined from getDiscount

**Complete CoD^Σ Trace:**

Step 1: → ParseError ↳ Source: Error log ↳ Data: TypeError at src/pricing/calculator.ts:67

Step 2: ⇄ IntelQuery("locate calculateTotal") ↳ Query: project-intel.mjs --search "calculateTotal" ↳ Data: Found in src/pricing/calculator.ts at line 62

Step 3: ⇄ IntelQuery("analyze symbols") ↳ Query: project-intel.mjs --symbols calculator.ts ↳ Data: calculateTotal at line 62, error at line 67 (5 lines in)

Step 4: → TargetedRead(lines 62-75) ↳ Source: sed -n '62,75p' calculator.ts ↳ Data: Line 67 calls getDiscount(code).discount without null check

Step 5: ⇄ IntelQuery("check getDiscount") ↳ Query: project-intel.mjs --symbols discountService.ts ↳ Data: getDiscount returns Discount | undefined

Step 6: → TargetedRead(getDiscount function) ↳ Source: sed -n '12,25p' discountService.ts ↳ Data: Returns undefined when code not found/inactive

Step 7: ⊕ MCPVerify("TypeScript best practices") ↳ Tool: Ref MCP ↳ Query: "TypeScript optional chaining undefined handling" ↳ Data: Use ?. operator for potentially undefined values

Step 8: ∘ Conclusion ↳ Logic: getDiscount returns undefined → accessing .discount throws TypeError ↳ Root Cause: src/pricing/calculator.ts:67 - missing null check ↳ Fix: Use optional chaining: getDiscount(code)?.discount ?? 0

Token Comparison:

• Reading full files: ~8600 tokens
• Intel + targeted reads: ~750 tokens
• Savings: 91%

Enforcement:

• Root cause identified with specific file:line
• Complete CoD^Σ trace documented
• MCP verification performed
• Fix approach validated

Phase 5: Generate Bug Report

Use @.claude/templates/bug-report.md to create comprehensive report:

---
bug_id: "checkout-discount-500"
severity: "critical"
status: "open"
assigned_to: "executor-agent"
---

# Bug Report: 500 Error on Checkout with Discount

## Symptom
[Full symptom from Phase 1]

## CoD^Σ Trace
[Complete trace from Phase 4]

## Root Cause
**Location:** src/pricing/calculator.ts:67

**Issue:** Missing null check before accessing .discount property

**Why It Fails:**
- getDiscount() returns Discount | undefined
- When discount code invalid/inactive, returns undefined
- Code attempts undefined.discount → TypeError

## Fix Specification
**Approach:** Add optional chaining

**Changes Required:**
```typescript
// Before (buggy)
const discountAmount = discountCode
  ? getDiscount(discountCode).discount * subtotal
  : 0

// After (fixed)
const discountAmount = discountCode
  ? (getDiscount(discountCode)?.discount ?? 0) * subtotal
  : 0

Reason:

• Optional chaining (?.) returns undefined if getDiscount returns undefined
• Nullish coalescing (?? 0) provides default value
• No TypeError, discount defaults to 0 for invalid codes

Verification

Test Plan:

it('handles invalid discount codes gracefully', () => {
  const cart = { items: [{ price: 100, quantity: 1 }] }
  const total = calculateTotal(cart, 'INVALID_CODE')
  expect(total).toBe(100) // No discount applied, no error
})

Acceptance Criteria:

• Invalid discount codes return subtotal (no discount)
• Valid discount codes still apply correctly
• No TypeError thrown

**File Naming:** `YYYYMMDD-HHMM-bug-<id>.md`

**Enforcement:**
- [ ] Bug report uses template
- [ ] CoD^Σ trace complete
- [ ] Root cause with file:line specified
- [ ] Fix proposal provided
- [ ] Verification plan included

## Common Error Patterns

### Pattern 1: React Infinite Re-render

**Symptom:**

Warning: Maximum update depth exceeded Component: LoginForm

**Debugging Process:**

1. Search for component: project-intel.mjs --search "LoginForm" --type tsx
2. Analyze symbols: Find useEffect hooks
3. Targeted read: Check dependency arrays
4. Common cause: useEffect depends on value it mutates
5. MCP verify: Ref MCP "React useEffect dependencies"
6. Fix: Remove mutated value from dependencies or use functional setState

### Pattern 2: N+1 Query Problem

**Symptom:**

Slow page load (10+ seconds) Dashboard with 100 users

**Debugging Process:**

1. Search for data fetch: project-intel.mjs --search "fetchUsers"
2. Analyze code: Look for loops around database queries
3. Common pattern: users.forEach(user => { const posts = await db.query("SELECT * FROM posts WHERE user_id = ?", user.id) }) // ← Query inside loop!
4. Fix: Single query with JOIN or WHERE IN clause

### Pattern 3: Memory Leak

**Symptom:**

Browser tab memory grows over time Eventually crashes

**Debugging Process:**

1. Search for event listeners: project-intel.mjs --search "addEventListener"
2. Check useEffect cleanup: Look for return functions
3. Common issue: Missing cleanup
4. MCP verify: Ref MCP "React useEffect cleanup"
5. Fix: Add cleanup function: useEffect(() => { window.addEventListener('resize', handler) return () => window.removeEventListener('resize', handler) // ← Cleanup }, [])

## Enforcement Rules

### Rule 1: Complete CoD^Σ Trace

**❌ Violation:**

The bug is in the discount calculation.

**✓ Correct:**

Root cause: src/pricing/calculator.ts:67

CoD^Σ Trace: Step 1: ParseError → TypeError at line 67 Step 2: IntelQuery → getDiscount returns undefined Step 3: MCPVerify → TypeScript docs confirm optional chaining needed Step 4: Conclusion → Missing null check causes error

### Rule 2: Intel Before Reading

**❌ Violation:**
```bash
# Read entire codebase looking for bug
cat src/**/*.ts  # Thousands of lines

✓ Correct:

# Intel-first approach
project-intel.mjs --search "calculateTotal"  # Find exact file
project-intel.mjs --symbols calculator.ts    # Find exact line
sed -n '62,75p' calculator.ts                # Read only relevant lines

Rule 3: Propose Fix with Verification

❌ Violation:

Fix: Change the code to handle undefined.

✓ Correct:

Fix: Use optional chaining at line 67:
  getDiscount(code)?.discount ?? 0

Verification:
- Test with invalid code (should return subtotal)
- Test with valid code (should apply discount)
- AC: No errors thrown for any input

Common Pitfalls

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

Version

Version: 1.0 Last Updated: 2025-10-19 Owner: Claude Code Intelligence Toolkit