debug

Follow the seven-step process: collect error information, reproduce the bug, diagnose the root cause, propose a minimal fix, apply the fix with a regression test, scan for similar patterns, and document the bug. Each step must complete before moving to the next.

Use find_referencing_symbols to trace the execution path backward from the failure point. Check for null access, race conditions, missing error handling, wrong data types, and stale state until the originating cause is confirmed.

It uses MCP code analysis tools: search_for_pattern to locate error messages, find_symbol to identify the exact function, and find_referencing_symbols to trace call paths. Raw file reads and grep are explicitly avoided.

Yes. After diagnosing the root cause, the proposed minimal fix is presented to the user and must be confirmed before implementation proceeds. This prevents unwanted code changes.

A debug-investigator subagent is spawned when the error spans multiple domains, the similar-pattern scan covers 10 or more files, or deep dependency tracing is needed. The spawn mechanism varies by vendor environment.

The regression test reproduces the original bug and verifies the fix, failing without the fix and passing with it. This guarantees the same defect cannot silently reappear in future changes.