⛔⛔⛔ 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

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