codeindex-debugging - SKILL.md Agent Skill

name: codeindex-debugging description: "Use when the user is debugging a bug, tracing an error, or asking why something fails. Examples: "Why is X failing?", "Where does this error come from?", "Trace this bug""

Debugging with CodeIndex

When to Use

"Why is this function failing?"
"Trace where this error comes from"
"Who calls this method?"
"This endpoint returns 500"
Investigating bugs, errors, or unexpected behavior

Workflow

1. codeindex_query({query: "<error or symptom>"})            → Find related execution flows
2. codeindex_context({name: "<suspect>"})                    → See callers/callees/processes
3. READ codeindex://repo/{name}/process/{name}                → Trace execution flow
4. codeindex_cypher({query: "MATCH path..."})                 → Custom traces if needed

In Conductor worktrees, "Index is stale" can be an overlay/canonical-checkout mismatch. Use scripts/codeindex-health.sh; only run scripts/codeindex-health.sh --repair when it reports the shared base index is stale. Verify branch-local code with source files/diffs.

Checklist

- [ ] Understand the symptom (error message, unexpected behavior)
- [ ] codeindex_query for error text or related code
- [ ] Identify the suspect function from returned processes
- [ ] codeindex_context to see callers and callees
- [ ] Trace execution flow via process resource if applicable
- [ ] codeindex_cypher for custom call chain traces if needed
- [ ] Read source files to confirm root cause

Debugging Patterns

Symptom	CodeIndex Approach
Error message	`codeindex_query` for error text → `context` on throw sites
Wrong return value	`context` on the function → trace callees for data flow
Intermittent failure	`context` → look for external calls, async deps
Performance issue	`context` → find symbols with many callers (hot paths)
Recent regression	`detect_changes` to see what your changes affect

Tools

codeindex_query — find code related to error:

codeindex_query({query: "payment validation error"})
→ Processes: CheckoutFlow, ErrorHandling
→ Symbols: validatePayment, handlePaymentError, PaymentException

codeindex_context — full context for a suspect:

codeindex_context({name: "validatePayment"})
→ Incoming calls: processCheckout, webhookHandler
→ Outgoing calls: verifyCard, fetchRates (external API!)
→ Processes: CheckoutFlow (step 3/7)

codeindex_cypher — custom call chain traces:

MATCH path = (a)-[:CodeRelation {type: 'CALLS'}*1..2]->(b:Function {name: "validatePayment"})
RETURN [n IN nodes(path) | n.name] AS chain

Example: "Payment endpoint returns 500 intermittently"

1. codeindex_query({query: "payment error handling"})
   → Processes: CheckoutFlow, ErrorHandling
   → Symbols: validatePayment, handlePaymentError

2. codeindex_context({name: "validatePayment"})
   → Outgoing calls: verifyCard, fetchRates (external API!)

3. READ codeindex://repo/my-app/process/CheckoutFlow
   → Step 3: validatePayment → calls fetchRates (external)

4. Root cause: fetchRates calls external API without proper timeout