1
2
3
4
5
6
7
8
9
10
11
12
13
14
|
{
"name": "debug-deep-dive",
"description": "Procedural framework for tracing complex state failures and isolating bugs across the module and VFS layers.",
"tags": [
"debugging",
"troubleshooting",
"state-trace",
"developer"
],
"category": "general",
"created": "2026-06-23T10:25:09.160Z",
"updated": "2026-06-24T21:58:03.530Z",
"content": "---\nname: debug-deep-dive\ndescription: Procedural framework for tracing complex state failures and isolating bugs across the module and VFS layers.\ntags: [debugging, troubleshooting, state-trace, developer]\n---\n\n## 1. Symptom Isolation\n- **Define the Delta**: Clearly identify the difference between *Expected Behavior* and *Actual Behavior*.\n- **Capture the State**:\n - Run `get_status` to check memory and loaded modules.\n - Use `list_modified_modules` to see if any local edits are interfering.\n - Check the current directory with `get_current_dir` and list files with `list_files`.\n\n## 2. Trace & Correlation\n- **Log Analysis**:\n - Inspect terminal output for specific error codes or stack traces.\n - If available, read relevant system logs in the VFS.\n- **Module Audit**:\n - Use `view_module` to inspect the source code of suspected modules.\n - Check for logical gaps, unhandled edge cases, or incorrect tool call signatures.\n- **Input/Output Mapping**:\n - Trace the flow: `User Input` $\\to$ `Skill/System Prompt` $\\to$ `Tool Call` $\\to$ `VFS/API Response` $\\to$ `Final Output`.\n - Identify exactly where the \"leak\" or \"mutation\" occurs.\n\n## 3. Controlled Reproduction (The Sandbox Method)\n- **Isolate the Variable**: \n - Create a dedicated test directory in VFS: `make_directory(\"test_debug_session\")`.\n - Copy minimal files required to reproduce the bug into this directory.\n- **Iterative Testing**:\n - Apply a hypothesis $\\to$ `edit_module` or `write_file` $\\to$ `test_module` (if applicable) or execute the command.\n - Observe if the behavior changes.\n\n## 4. Verification & Hardening\n- **Regression Check**: Once the fix is found, try to break it using edge-case inputs (empty strings, oversized files, unexpected types).\n- **Cleanup**: \n - Remove debug files/directories created during the process.\n - Use `reload_module` if the fix was applied to the source.\n- **Documentation**: If the bug was architectural, create or update a skill to prevent its recurrence."
}
|
