AgentSkillsCN

noodlbox-debugging

排查错误、追踪 Bug、深究根本原因。探究代码为何出错、追溯执行路径、解决意外行为,找出函数返回错误值的真正缘由。但切勿用于探索陌生代码(请使用 exploring-codebases)或规划变更(请使用 change-planning)。

SKILL.md
--- frontmatter
name: noodlbox-debugging
description: >-
  Debug errors, trace bugs, find root causes. Investigate why code fails, trace
  execution paths, troubleshoot unexpected behavior, find why functions return
  wrong values. NOT for exploring unfamiliar code (use exploring-codebases) or
  planning changes (use change-planning).
metadata:
  author: noodlbox
  version: "{{VERSION}}"

Debugging

Investigate bugs by understanding code relationships and tracing execution paths.

Quick Start

code
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.

code
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.

code
noodlbox_detect_impact(
  repository: "current",
  change_scope: "all",
  include_content: true
)

noodlbox_raw_cypher_query

Trace callers and callees of suspect functions.

cypher
-- 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

For more Cypher patterns, see shared/cypher-patterns.md.

Workflow Checklist

Investigate a Bug

code
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"

code
Step 1: Find payment-related error handling
noodlbox_query_with_context(
  repository: "current",
  q: "payment error handling exception",
  task_context: "debugging intermittent 500 errors",
  current_goal: "find error handling code",
  limit: 5
)

→ Results:
  Process: "Payment validation flow"
  ├── validatePayment (src/payments/validator.ts:42)
  ├── handlePaymentError (src/payments/errors.ts:15)
  └── PaymentException (src/payments/exceptions.ts:8)

Step 2: Trace who calls validatePayment
noodlbox_raw_cypher_query(
  repository: "current",
  cypher: "MATCH (caller)-[:CALLS]->(fn:CODE_SYMBOL {name: 'validatePayment'}) RETURN caller.name, caller.file_path"
)

→ Results:
  processCheckout (src/checkout/handler.ts)
  webhookHandler (src/webhooks/payment.ts)

Step 3: Check what validatePayment calls
noodlbox_raw_cypher_query(
  repository: "current",
  cypher: "MATCH (fn:CODE_SYMBOL {name: 'validatePayment'})-[:CALLS]->(callee) RETURN callee.name, callee.file_path"
)

→ Results:
  verifyCardExpiry (src/payments/card.ts)
  checkAmount (src/payments/validator.ts)
  fetchRates (src/external/currency.ts)  ← External call!

Step 4: Hypothesis
fetchRates calls external API → intermittent failures
Read src/external/currency.ts to verify error handling

Step 5: Root cause found
fetchRates doesn't handle timeout properly

Checklist for this example:

code
- [x] Understand symptom (500 error, intermittent)
- [x] Search for related code (payment error handling)
- [x] Identify failing component (validatePayment flow)
- [x] Trace callers (processCheckout, webhookHandler)
- [x] Trace callees (fetchRates - external API)
- [x] Form hypothesis (external API timeout)
- [x] Read source (currency.ts - missing timeout handling)

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 skill
Plan safe changeschange-planning skill
Large refactoringrefactoring skill
Generate documentationgenerating-documentation skill