noodlbox

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 code

Tool 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 20

Workflow 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 verify

Example: 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

SymptomApproach
Error messageSearch for error text, trace throw sites
Wrong return valueTrace data flow through callees
Intermittent failureLook for external calls, race conditions
Performance issueFind hot paths via centrality
Recent regressionUse detect_impact to find recent changes

When to Use Something Else

NeedUse Instead
Explore unfamiliar codeExploring Codebases
Plan safe changesChange Planning
Large refactoringRefactoring
Generate documentationGenerating Documentation

On this page