About gitnexus-debugging
gitnexus-debugging is a GitNexus workflow skill for developers and coding agents investigating errors or unexpected behavior. It guides code searches, symbol context checks, and execution tracing to help locate where a failure occurs.
Key features
- 01Search code and execution flows
- 02Inspect symbol callers and callees
- 03Trace repository processes
- 04Build custom call-chain queries
- 05Find shortest paths between symbols
Use cases
- 01Investigate an error message or failing function
- 02Trace an endpoint's execution path
- 03Locate where a call chain breaks
- 04Check recent changes for regressions
MCP support
The skill uses GitNexus MCP tools such as query, context, cypher, and trace, and reads process resources to follow code execution.
Install
Copy the command and run it in a terminal.
npx skills add https:/After installing, type/gitnexus-debuggingin Claude Code to confirm it loaded.
Details
From the project READMEDebugging 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. query({search_query: "<error or symptom>"}) → Find related execution flows
2. context({name: "<suspect>"}) → See callers/callees/processes
3. READ gitnexus://repo/{name}/process/{name} → Trace execution flow
4. cypher({statement: "MATCH path..."}) → Custom traces if needed
If "Index is stale" → run
node .gitnexus/run.cjs analyzein terminal.
Checklist
- [ ] Understand the symptom (error message, unexpected behavior)
- [ ] query for error text or related code
- [ ] Identify the suspect function from returned processes
- [ ] context to see callers and callees
- [ ] Trace execution flow via process resource if applicable
- [ ] cypher for custom call chain traces if needed
- [ ] Read source files to confirm root cause
Debugging Patterns
| Symptom | GitNexus Approach |
|---|---|
| Error message | 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 |
| "How does A reach B?" | trace between the two symbols — shortest call chain in one call |
Tools
query — find code related to error:
query({search_query: "payment validation error"})
→ Processes: CheckoutFlow, ErrorHandling
→ Symbols: validatePayment, handlePaymentError, PaymentException
context — full context for a suspect:
context({name: "validatePayment"})
→ Incoming calls: processCheckout, webhookHandler
→ Outgoing calls: verifyCard, fetchRates (external API!)
→ Processes: CheckoutFlow (step 3/7)
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
trace — shortest call chain between two symbols ("how does A reach B?"), one call instead of chaining context hops:
trace({ from: "processCheckout", to: "fetchRates" })
→ status: ok, hopCount: 3
→ hops: processCheckout → validatePayment → verifyCard → fetchRates
→ edges: CALLS (1.0), CALLS (0.95), CALLS (1.0)
When no path exists, trace reports the furthest reachable node — exactly where the chain breaks (dynamic dispatch, reflection, or an external boundary).
Example: "Payment endpoint returns 500 intermittently"
1. query({search_query: "payment error handling"})
→ Processes: CheckoutFlow, ErrorHandling
→ Symbols: validatePayment, handlePaymentError
2. context({name: "validatePayment"})
→ Outgoing calls: verifyCard, fetchRates (external API!)
3. READ gitnexus://repo/my-app/process/CheckoutFlow
→ Step 3: validatePayment → calls fetchRates (external)
4. Root cause: fetchRates calls external API without proper timeout