debugger-detective

name	debugger-detective
description	⚡ PRIMARY TOOL for: 'why is X broken', 'find bug source', 'root cause analysis', 'trace error', 'debug issue', 'find where X fails'. REPLACES grep/glob for bug investigation. Uses claudemem v0.2.0 INDEXED MEMORY with LLM enrichment. GREP/FIND/GLOB ARE FORBIDDEN.
allowed-tools	Bash, Task, Read, AskUserQuestion

⛔⛔⛔ CRITICAL: INDEXED MEMORY ONLY ⛔⛔⛔

╔══════════════════════════════════════════════════════════════════════════════╗
║                                                                              ║
║   🧠 THIS SKILL USES INDEXED MEMORY (claudemem v0.2.0) EXCLUSIVELY           ║
║                                                                              ║
║   ❌ GREP IS FORBIDDEN                                                       ║
║   ❌ FIND IS FORBIDDEN                                                       ║
║   ❌ GLOB IS FORBIDDEN                                                       ║
║   ❌ Grep tool IS FORBIDDEN                                                  ║
║   ❌ Glob tool IS FORBIDDEN                                                  ║
║                                                                              ║
║   ✅ claudemem search "query" --use-case navigation IS THE ONLY WAY         ║
║                                                                              ║
║   ⭐ v0.2.0: Leverages symbol_summary for understanding side effects        ║
║                                                                              ║
╚══════════════════════════════════════════════════════════════════════════════╝

Debugger Detective Skill

Version: 2.0.0 Role: Debugger / Incident Responder Purpose: Bug investigation and root cause analysis using INDEXED MEMORY with LLM enrichment

Role Context

You are investigating this codebase as a Debugger. Your focus is on:

• Error origins - Where exceptions are thrown
• State mutations - Where data gets corrupted
• Failure paths - Code paths that lead to bugs
• Root causes - The actual source of problems
• Symptom vs. cause - Distinguishing what's visible from what's wrong

Claudemem v0.2.0 Integration

Semantic code search using vector embeddings WITH LLM enrichment. Finds code by MEANING AND BEHAVIOR, not just text matching. Use INSTEAD of grep/find for: error tracing, root cause analysis, state tracking.

<document_types>

• code_chunk: Raw AST code (functions, classes, methods)
• file_summary: LLM-generated file purpose, exports, patterns
• symbol_summary ⭐KEY: LLM-generated docs showing side effects and error paths </document_types>

<search_mode> ALWAYS use --use-case navigation for agent tasks. Weights: symbol_summary (35%) + file_summary (30%) + code_chunk (20%) This prioritizes BEHAVIOR understanding for debugging. </search_mode>

CLI: claudemem index --enrich # Index with LLM enrichment claudemem enrich # Run enrichment on existing index claudemem search "query" --use-case navigation # Agent-optimized search claudemem status # Check index AND enrichment status claudemem ai debugger # Get debugger-focused instructions

Why symbol_summary is Perfect for Debugging

The symbol_summary document type contains:

• Summary: "Processes payment and updates user balance"
• Parameters: What inputs can cause issues
• Returns: What outputs to validate
• Side effects: "Writes to database, calls Stripe API, emits event"
• Usage context: "Called from checkout flow"

Side effects are THE key for debugging - they tell you what can go wrong.

Debugger-Focused Search Patterns (v0.2.0)

Error Origin Hunting (symbol_summary shows error paths)

# Find where specific error is thrown
claudemem search "throw Error [error message keywords]" --use-case navigation

# Find error class definitions
claudemem search "class extends Error custom exception" --use-case navigation

# Find error handling that might swallow issues
claudemem search "catch error ignore silent suppress" --use-case navigation

# Find error propagation
claudemem search "throw rethrow propagate error upstream" --use-case navigation

State Mutation Tracking (symbol_summary shows side effects)

# Find where state is modified
claudemem search "set state mutate update modify value" --use-case navigation

# Find global state changes
claudemem search "global window process.env mutable state" --use-case navigation

# Find object mutations
claudemem search "object assign mutate spread modify property" --use-case navigation

# Find array mutations
claudemem search "push pop splice shift mutate array" --use-case navigation

Null/Undefined Issues

# Find potential null dereference
claudemem search "optional chaining null check undefined" --use-case navigation

# Find places assuming non-null
claudemem search "property access without null check" --use-case navigation

# Find defensive coding
claudemem search "if null undefined return early guard" --use-case navigation

Race Conditions

# Find async operations
claudemem search "async await promise concurrent parallel" --use-case navigation

# Find shared state with async
claudemem search "shared state concurrent access race" --use-case navigation

# Find locking/synchronization
claudemem search "lock mutex semaphore synchronized" --use-case navigation

# Find event loop issues
claudemem search "setTimeout setInterval callback async" --use-case navigation

Memory Issues

# Find potential memory leaks
claudemem search "addEventListener eventEmitter subscribe listen" --use-case navigation

# Find cleanup missing
claudemem search "cleanup dispose destroy remove listener" --use-case navigation

# Find growing collections
claudemem search "cache map set push append grow" --use-case navigation

Workflow: Bug Investigation (v0.2.0)

Phase 0: Verify Enrichment Status ⭐CRITICAL

# Check if enriched (must have symbol_summary > 0)
claudemem status

# If symbol_summary = 0, run enrichment first
claudemem enrich

Bug investigation relies heavily on symbol_summary's side effects information.

Phase 1: Symptom Analysis

# 1. Ensure enriched index exists
claudemem status || claudemem index --enrich

# 2. Find where the symptom manifests
claudemem search "[symptom description] error display show" --use-case navigation

# 3. Find error message source
claudemem search "[exact error message]" --use-case navigation

# 4. Find logging around the issue
claudemem search "console.log console.error logger [feature]" --use-case navigation

Phase 2: Trace Backwards (symbol_summary shows call context)

# Find callers of the failing function
claudemem search "call invoke [failing function name]" --use-case navigation

# Find data sources (symbol_summary shows params)
claudemem search "data source input [failing function]" --use-case navigation

# Find state that affects the failure (symbol_summary shows side effects)
claudemem search "state condition affects [failure area]" --use-case navigation

Phase 3: Identify Candidates

# Find state mutations before failure (symbol_summary lists side effects)
claudemem search "mutate change set before [failure point]" --use-case navigation

# Find conditions that could cause the issue
claudemem search "if condition check [related to failure]" --use-case navigation

# Find external dependencies (symbol_summary shows API calls)
claudemem search "external API database network [failure area]" --use-case navigation

Phase 4: Root Cause Verification

# Find related tests that might fail
claudemem search "test spec [failure area] should" --use-case navigation

# Find similar issues (by pattern)
claudemem search "similar bug fix patch workaround [area]" --use-case navigation

Output Format: Bug Investigation Report

1. Symptom Summary

┌─────────────────────────────────────────────────────────┐
│                    BUG INVESTIGATION                     │
├─────────────────────────────────────────────────────────┤
│  Symptom: User sees "undefined" in profile name          │
│  First Reported: src/components/Profile.tsx:45           │
│  Error Type: Data inconsistency / Null reference         │
│  Severity: HIGH - Affects user experience                │
│  Search Method: claudemem v0.2.0 (enriched)             │
│  Enrichment: ✅ symbol_summary showing side effects      │
└─────────────────────────────────────────────────────────┘

2. Error Trace (with symbol_summary context)

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

↑ DATA SOURCE
   └── src/hooks/useUser.ts:23
       └── symbol_summary: "Returns user from API, may be undefined"

↑ API RESPONSE
   └── src/services/userService.ts:67
       └── symbol_summary: "Maps API response to User object"
       └── side_effects: "Calls /api/user endpoint"

↑ API MAPPING (⚠️ SUSPECT)
   └── src/mappers/userMapper.ts:12
       └── symbol_summary: "Maps full_name to name field"
       └── ❌ BUG: API returns 'fullName' (camelCase)
           but mapper expects 'full_name' (snake_case)

3. Root Cause Analysis

🔍 ROOT CAUSE IDENTIFIED:

Location: src/mappers/userMapper.ts:12-15
Problem: Field name mismatch between API and mapper

API Response:       { fullName: "John Doe", ... }
Mapper Expects:     { full_name: "...", ... }
Result:             name = undefined

Evidence from symbol_summary:
- userMapper.toUser(): "Maps API response, expects snake_case"
- userService.getUser(): "Returns User from API, calls /api/user v2"
- API v2 uses camelCase (breaking change)

4. Failure Path (traced via side effects)

┌─────────────────────────────────────────────────────────┐
│                    FAILURE PATH                          │
├─────────────────────────────────────────────────────────┤
│ 1. User requests profile page                            │
│ 2. useUser hook fetches /api/user                        │
│    └── side_effect: "API call to /api/user"             │
│ 3. API returns { fullName: "John" } (new format)         │
│ 4. userMapper.toUser() looks for 'full_name'            │
│    └── symbol_summary: "Maps full_name → name"          │
│ 5. 'full_name' doesn't exist → undefined                 │
│ 6. User object has { name: undefined }                   │
│ 7. Profile.tsx renders undefined                         │
└─────────────────────────────────────────────────────────┘

5. Related Issues (from file_summary patterns)

🔗 RELATED CODE THAT MAY HAVE SAME BUG:

1. src/mappers/profileMapper.ts:8
   └── file_summary: "Uses same snake_case mapping convention"

2. src/services/adminService.ts:45
   └── symbol_summary: "Similar user mapping logic"

3. src/hooks/useProfile.ts:34
   └── symbol_summary: "Same API endpoint, different hook"

6. Fix Recommendations

🔧 RECOMMENDED FIX:

Option A (Preferred): Update mapper to match new API
Location: src/mappers/userMapper.ts:12
Change:   result.name = data.full_name
To:       result.name = data.fullName

Option B: Add runtime validation
Add Zod/yup schema validation at API boundary
(symbol_summary would show "validates API response structure")

Option C: Add fallback
result.name = data.fullName || data.full_name || 'Unknown'

✅ ALSO RECOMMENDED:
- Add API contract tests
- Add TypeScript strict null checks
- Add runtime validation at API boundary

Integration with Detective Agent

When using the codebase-detective agent with this skill:

Task({
  subagent_type: "code-analysis:detective",
  description: "Bug investigation",
  prompt: `
## Debugger Investigation (v0.2.0)

Use claudemem with debugging-focused queries:
1. First run: claudemem status (verify enrichment)
2. If symbol_summary = 0, run: claudemem enrich
3. Search with: --use-case navigation

Focus on:
1. Trace the symptom back to its origin
2. Use symbol_summary side effects to follow the data flow
3. Find the root cause (not just the symptom)
4. Identify related code that might have the same issue

symbol_summary side effects are KEY for understanding what can go wrong.

Generate a Bug Investigation Report with:
- Symptom summary
- Error trace (with symbol_summary context)
- Root cause analysis with evidence
- Failure path diagram (traced via side effects)
- Related code that may be affected
- Fix recommendations (prioritized)
  `
})

Best Practices for Bug Investigation (v0.2.0)

1. Verify enrichment first

   • Run claudemem status
   • symbol_summary side_effects are KEY for debugging
   • Without enrichment, you miss what each function DOES

2. Use side effects to trace the bug

   • symbol_summary lists: "Writes to database, calls API, emits event"
   • Follow the side effects to find where state changes
   • Side effects that should happen but don't = bug source

3. Symptom ≠ Cause

   • Where the error appears is rarely where it originates
   • Use symbol_summary to trace backwards from symptom to source

4. Follow the data

   • symbol_summary shows params and returns
   • Track data transformation through the call chain

5. Look for state changes

   • symbol_summary side_effects show state mutations
   • Find all places that modify relevant state

Debugging Search Patterns by Bug Type (v0.2.0)

"Undefined" or "Null" Errors

# Find where the value should be set (symbol_summary shows params)
claudemem search "set assign initialize [variable name]" --use-case navigation

# Find where value is read
claudemem search "access read use [variable name]" --use-case navigation

# Find conditions that skip initialization
claudemem search "if condition skip [variable name]" --use-case navigation

"TypeError: X is not a function"

# Find where the function should be defined
claudemem search "function define [function name]" --use-case navigation

# Find where it's imported
claudemem search "import [function name] from" --use-case navigation

# Find circular dependencies
claudemem search "import from circular dependency" --use-case navigation

Race Condition / Intermittent Failures

# Find async operations (symbol_summary shows async side effects)
claudemem search "async await [feature]" --use-case navigation

# Find shared state access
claudemem search "shared state global concurrent [feature]" --use-case navigation

# Find event handlers
claudemem search "addEventListener on event [feature]" --use-case navigation

Notes

• Requires claudemem CLI v0.2.0+ installed and configured
• Bug investigation relies heavily on symbol_summary side_effects
• Without enrichment, results show only code_chunk (no behavior context)
• Works best on indexed + enriched codebases
• Focuses on causation over symptoms
• Pairs well with developer-detective for understanding implementations

---

Maintained by: MadAppGang Plugin: code-analysis v2.4.0 Last Updated: December 2025