Debugging
Trace bugs and find root causes using the knowledge graph
Investigate bugs by understanding code relationships and tracing execution paths.
Invoke with: /noodlbox:debugging
Quick Start
1. noodlbox_query_with_context → Find code related to the error
2. READ map://current/process/[id] → Trace execution flow
3. noodlbox_raw_cypher_query → Find callers/callees of suspect codeTool Reference
noodlbox_query_with_context
Find code semantically related to the error or symptom.
noodlbox_query_with_context(
repository: "current",
q: "payment validation error handling",
task_context: "debugging payment failures",
current_goal: "find where validation errors originate",
search_intention: "trace error path",
limit: 5,
max_symbols: 10
)noodlbox_detect_impact
Find what recent changes might have introduced the bug.
noodlbox_detect_impact(
repository: "current",
change_scope: "all",
include_content: true
)noodlbox_raw_cypher_query
Trace callers and callees of suspect functions.
-- Who calls the failing function?
MATCH (caller)-[:CALLS]->(target:CODE_SYMBOL {name: "validatePayment"})
RETURN caller.name, caller.file_path LIMIT 20
-- What does the failing function call?
MATCH (source:CODE_SYMBOL {name: "validatePayment"})-[:CALLS]->(target)
RETURN target.name, target.file_path LIMIT 20Workflow Checklist
Bug Investigation:
- [ ] Understand the symptom (error message, unexpected behavior)
- [ ] Search for related code with query_with_context
- [ ] Identify the failing function/component
- [ ] Trace callers to find entry points
- [ ] Trace callees to find dependencies
- [ ] Check recent changes with detect_impact
- [ ] Read source files for root cause
- [ ] Form hypothesis and verifyExample: Debug Payment Failure
Task: "The payment endpoint returns a 500 error intermittently"
Find payment error handling
"Find code related to payment error handling"
Uses: noodlbox_query_with_context
Results show: validatePayment, handlePaymentError, PaymentException
Trace callers
"Who calls validatePayment?"
Uses: noodlbox_raw_cypher_query
Callers: processCheckout, webhookHandler
Trace callees
"What does validatePayment call?"
Uses: noodlbox_raw_cypher_query
Callees: verifyCardExpiry, checkAmount, fetchRates (external call!)
Form hypothesis
fetchRates calls external API → intermittent failures
Read src/external/currency.ts to verify error handling
Root cause found
fetchRates doesn't handle timeout properly
Debugging Patterns
| Symptom | Approach |
|---|---|
| Error message | Search for error text, trace throw sites |
| Wrong return value | Trace data flow through callees |
| Intermittent failure | Look for external calls, race conditions |
| Performance issue | Find hot paths via centrality |
| Recent regression | Use detect_impact to find recent changes |
When to Use Something Else
| Need | Use Instead |
|---|---|
| Explore unfamiliar code | Exploring Codebases |
| Plan safe changes | Change Planning |
| Large refactoring | Refactoring |
| Generate documentation | Generating Documentation |