debugger-detective

What this skill does

# ⛔⛔⛔ CRITICAL: AST STRUCTURAL ANALYSIS ONLY ⛔⛔⛔

```
╔══════════════════════════════════════════════════════════════════════════════╗
║                                                                              ║
║   🧠 THIS SKILL USES claudemem v0.3.0 AST ANALYSIS EXCLUSIVELY               ║
║                                                                              ║
║   ❌ GREP IS FORBIDDEN                                                       ║
║   ❌ FIND IS FORBIDDEN                                                       ║
║   ❌ GLOB IS FORBIDDEN                                                       ║
║                                                                              ║
║   ✅ claudemem --nologo context <name> --raw FOR FULL CALL CHAIN            ║
║   ✅ claudemem --nologo callers <name> --raw TO TRACE BACK TO SOURCE        ║
║   ✅ claudemem --nologo callees <name> --raw TO TRACE FORWARD               ║
║                                                                              ║
║   ⭐ v0.3.0: context shows full call chain for root cause analysis          ║
║                                                                              ║
╚══════════════════════════════════════════════════════════════════════════════╝
```

# Debugger Detective Skill

**Version:** 3.3.0
**Role:** Debugger / Incident Responder
**Purpose:** Bug investigation and root cause analysis using AST call chain tracing with blast radius impact analysis

## Role Context

You are investigating this codebase as a **Debugger**. Your focus is on:
- **Error origins** - Where exceptions are thrown
- **Call chains** - How execution flows to the failure point
- **State mutations** - What changed the data before failure
- **Root causes** - The actual source of problems (not just symptoms)
- **Impact radius** - What else might be affected

## Why `context` is Perfect for Debugging

The `context` command shows you:
- **Symbol definition** = Where the buggy code is
- **Callers** = How we got here (trace backwards)
- **Callees** = What happens next (trace forward)
- **Full call chain** = Complete picture for root cause analysis

## Debugger-Focused Commands (v0.3.0)

### Find the Bug Location

```bash
# Find the function mentioned in error
claudemem --nologo symbol authenticate --raw

# Get full context (callers + callees)
claudemem --nologo context authenticate --raw
```

### Trace Back to Source (callers)

```bash
# Who called this function? (trace backwards)
claudemem --nologo callers authenticate --raw

# Follow the chain backwards
claudemem --nologo callers LoginController --raw
claudemem --nologo callers handleRequest --raw
```

### Trace Forward to Effect (callees)

```bash
# What does this function call? (trace forward)
claudemem --nologo callees authenticate --raw

# Find where state changes happen
claudemem --nologo callees updateSession --raw
```

### Blast Radius Analysis (v0.4.0+ Required)

```bash
# After finding the bug, check what else is affected
IMPACT=$(claudemem --nologo impact buggyFunction --raw)

if [ -z "$IMPACT" ] || echo "$IMPACT" | grep -q "No callers"; then
  echo "No static callers - bug is isolated (or dynamically called)"
else
  echo "$IMPACT"
  echo ""
  echo "This shows:"
  echo "- Direct callers (immediately affected)"
  echo "- Transitive callers (potentially affected)"
  echo "- Complete list for testing after fix"
fi
```

**Use for**:
- Post-fix verification (test all impacted code)
- Regression prevention (know what to test)
- Incident documentation (impact scope)

**Limitations:**
Event-driven/callback architectures may have callers not visible to static analysis.

### Error Origin Hunting

```bash
# Map error handling code
claudemem --nologo map "throw error exception" --raw

# Find specific error types
claudemem --nologo symbol AuthenticationError --raw

# Who throws this error?
claudemem --nologo callers AuthenticationError --raw
```

### State Mutation Tracking

```bash
# Find where state changes
claudemem --nologo map "set state update mutate" --raw

# Find the mutation function
claudemem --nologo symbol updateUserState --raw

# Who calls this mutation?
claudemem --nologo callers updateUserState --raw
```

## PHASE 0: MANDATORY SETUP

### Step 1: Verify claudemem v0.3.0

```bash
which claudemem && claudemem --version
# Must be 0.3.0+
```

### Step 2: If Not Installed → STOP

Use AskUserQuestion (see ultrathink-detective for template)

### Step 3: Check Index Status

```bash
# Check claudemem installation and index
claudemem --version && ls -la .claudemem/index.db 2>/dev/null
```

### Step 3.5: Check Index Freshness

Before proceeding with investigation, verify the index is current:

```bash
# First check if index exists
if [ ! -d ".claudemem" ] || [ ! -f ".claudemem/index.db" ]; then
  # Use AskUserQuestion to prompt for index creation
  # Options: [1] Create index now (Recommended), [2] Cancel investigation
  exit 1
fi

# Count files modified since last index
STALE_COUNT=$(find . -type f \( -name "*.ts" -o -name "*.tsx" -o -name "*.js" -o -name "*.jsx" -o -name "*.py" -o -name "*.go" -o -name "*.rs" \) \
  -newer .claudemem/index.db 2>/dev/null | grep -v "node_modules" | grep -v ".git" | grep -v "dist" | grep -v "build" | wc -l)
STALE_COUNT=$((STALE_COUNT + 0))  # Normalize to integer

if [ "$STALE_COUNT" -gt 0 ]; then
  # Get index time with explicit platform detection
  if [[ "$OSTYPE" == "darwin"* ]]; then
    INDEX_TIME=$(stat -f "%Sm" -t "%Y-%m-%d %H:%M" .claudemem/index.db 2>/dev/null)
  else
    INDEX_TIME=$(stat -c "%y" .claudemem/index.db 2>/dev/null | cut -d'.' -f1)
  fi
  INDEX_TIME=${INDEX_TIME:-"unknown time"}

  # Get sample of stale files
  STALE_SAMPLE=$(find . -type f \( -name "*.ts" -o -name "*.tsx" \) \
    -newer .claudemem/index.db 2>/dev/null | grep -v "node_modules" | grep -v ".git" | head -5)

  # Use AskUserQuestion (see template in ultrathink-detective)
fi
```

### Step 4: Index if Needed

```bash
claudemem index
```

---

## Workflow: Bug Investigation (v0.3.0)

### Phase 1: Locate the Symptom

```bash
# Find where the error appears
claudemem --nologo map "error message keywords" --raw

# Or find the specific function
claudemem --nologo symbol failingFunction --raw
```

### Phase 2: Get Full Context

```bash
# Get callers + callees in one command
claudemem --nologo context failingFunction --raw
```

### Phase 3: Trace Backwards (Find Root Cause)

```bash
# For each caller, check if it's the source
claudemem --nologo callers caller1 --raw
claudemem --nologo callers caller2 --raw

# Keep tracing until you find the root
```

### Phase 4: Verify the Chain

```bash
# Once you suspect a root cause, verify the path
claudemem --nologo callees suspectedRoot --raw

# Does it lead to the symptom?
```

### Phase 5: Check Impact

```bash
# What else calls the buggy code?
claudemem --nologo callers buggyFunction --raw

# These are all potentially affected
```

## Output Format: Bug Investigation Report

### 1. Symptom Summary

```
┌─────────────────────────────────────────────────────────┐
│                    BUG INVESTIGATION                     │
├─────────────────────────────────────────────────────────┤
│  Symptom: User sees "undefined" in profile name          │
│  Location: src/components/Profile.tsx:45                │
│  Error Type: Data inconsistency / Null reference         │
│  Search Method: claudemem v0.3.0 (AST call chain)       │
└─────────────────────────────────────────────────────────┘
```

### 2. Call Chain Trace

```
❌ SYMPTOM: undefined rendered
   └── src/components/Profile.tsx:45
       └── user.name is undefined

↑ CALLER CHAIN (trace backwards):
   └── useUser hook (src/hooks/useUser.ts:23)
       ↑
   └── fetchUser API (src/api/user.ts:67)
       ↑
   └── userMapper (src/mappers/user.ts:12)
       ↑
🔍 ROOT CAUSE FOUND HERE
```

### 3. Root Cause Analysis

```
🔍 ROOT CAUSE IDENTIFIED:

Location: src/mappers/user.ts:12
Problem: Field name mismatch

API Response:       { fullName: "John