1 files changed, 14 insertions, 0 deletions
diff --git a/skills/debug-deep-dive.json b/skills/debug-deep-dive.json
new file mode 100644
index 0000000..ea9250c
--- /dev/null
+++ b/skills/debug-deep-dive.json
@@ -0,0 +1,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."
+}
+\ No newline at end of file