gitnexus-debugging

name	gitnexus-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 GitNexus

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. gitnexus_query({query: "<error or symptom>"})    → Find related execution flows
2. gitnexus_context({name: "<suspect>"})             → See callers/callees/processes
3. gitnexus_cypher({query: "MATCH path..."})         → Custom traces if needed
4. Read source files to confirm root cause

If index is stale → run /gitnexus analyze to rebuild.

Debugging Patterns

Symptom	GitNexus Approach
Error message	gitnexus_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	gitnexus_detect_changes to see what your changes affect

Checklist

- [ ] Understand the symptom (error message, unexpected behavior)
- [ ] gitnexus_query for error text or related code
- [ ] Identify the suspect function from returned processes
- [ ] gitnexus_context to see callers and callees
- [ ] gitnexus_cypher for custom call chain traces if needed
- [ ] Read source files to confirm root cause

Tools

gitnexus_query — find code related to error:

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

gitnexus_context — full context for a suspect:

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

gitnexus_cypher — custom call chain traces:

gitnexus_cypher({query: "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. gitnexus_query({query: "payment error handling"})
   → Processes: CheckoutFlow, ErrorHandling
   → Symbols: validatePayment, handlePaymentError

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

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