// 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"
Use when the user needs to run GitNexus CLI commands like analyze/index a repo, check status, clean the index, generate a wiki, or list indexed repos. Examples: "Index this repo", "Reanalyze the codebase", "Generate a wiki"
Use when the user asks how code works, wants to understand architecture, trace execution flows, or explore unfamiliar parts of the codebase. Examples: "How does X work?", "What calls this function?", "Show me the auth flow"
Use when the user wants to know what will break if they change something, or needs safety analysis before editing code. Examples: "Is it safe to change X?", "What depends on this?", "What will break?"
Use when the user wants to rename, extract, split, move, or restructure code safely. Examples: "Rename this function", "Extract this into a module", "Refactor this class", "Move this to a separate file"
Use when the user asks about GitNexus itself — available tools, how to query the knowledge graph, graph schema, or workflow reference.
Trace bugs through call chains using knowledge graph
| 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" |
IMPORTANT — How to use GitNexus: GitNexus is a standalone CLI tool. Run it directly via
gitnexus <command>in the Bash tool. Do NOT usemcpl call gitnexus ....
Multi-repo note: Always pass
--repo <name>to every command to avoid "multiple repositories" errors.
1. gitnexus query "<error or symptom>" --repo <name> → Find related execution flows
2. gitnexus context "<suspect>" --repo <name> → See callers/callees/processes
3. gitnexus cypher "MATCH path..." --repo <name> → Custom call-chain traces if needed
4. Read the actual source files to confirm root cause
If "Index is stale" → run
gitnexus analyzein terminal.
- [ ] 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
| Symptom | GitNexus Approach |
|---|---|
| Error message | gitnexus query for error text → gitnexus context on throw sites |
| Wrong return value | gitnexus context on the function → trace callees for data flow |
| Intermittent failure | gitnexus context → look for external calls, async deps |
| Performance issue | gitnexus context → find symbols with many callers (hot paths) |
| Recent regression | gitnexus detect-changes to see what your changes affect |
gitnexus query — find code related to error:
gitnexus query "payment validation error" --repo my-app
# → Processes: CheckoutFlow, ErrorHandling
# → Symbols: validatePayment, handlePaymentError, PaymentException
gitnexus context — full context for a suspect:
gitnexus context "validatePayment" --repo my-app
# → Incoming calls: processCheckout, webhookHandler
# → Outgoing calls: verifyCard, fetchRates (external API!)
# → Processes: CheckoutFlow (step 3/7)
gitnexus cypher — custom call chain traces:
gitnexus cypher 'MATCH path = (a)-[:CodeRelation {type: "CALLS"}*1..2]->(b:Function {name: "validatePayment"}) RETURN [n IN nodes(path) | n.name] AS chain' --repo my-app
# 1. Find related execution flows
gitnexus query "payment error handling" --repo my-app
# → Processes: CheckoutFlow, ErrorHandling
# → Symbols: validatePayment, handlePaymentError
# 2. Inspect the suspect
gitnexus context "validatePayment" --repo my-app
# → Outgoing calls: verifyCard, fetchRates (external API!)
# 3. Trace the full call chain
gitnexus cypher 'MATCH path = (a)-[:CodeRelation*1..3]->(b:Function {name: "fetchRates"}) RETURN path' --repo my-app
# 4. Root cause: fetchRates calls external API without proper timeout