{
"name": "deep-debugging",
"category": "methodology",
"priority": "critical",
"trigger_patterns": [
"works in X but not Y",
"module resolution",
"bundler error",
"cross-runtime issue",
"version mismatch",
"compatibility issue",
"cannot find module",
"unexpected behavior",
"complex bug",
"multi-layer problem"
],
"requires": [
"Read tool access",
"Bash for testing",
"Grep for source tracing"
],
"when_to_use": [
"Bug spans multiple layers (runtime, bundler, module system)",
"Error message unclear or misleading",
"Simple solutions already tried and failed",
"Behavior differs between environments",
"Root cause not immediately obvious"
],
"when_not_to_use": [
"Simple typos or syntax errors",
"Well-documented API usage errors",
"Single-layer problems with clear error messages"
],
"outputs": [
"Root cause analysis document",
"Minimal reproduction test cases",
"Solution with trade-off analysis",
"Debugging artifact documentation"
],
"examples": [
{
"issue": "Pear MODULE_NOT_FOUND for 'buffer'",
"root_cause": "Static bundler can't resolve import attributes mapping",
"solution": "Compatibility shim bridging Node.js buffer to bare-buffer",
"artifact": "hyper-fleeky/hyper-wallet/DEBUGGING_LESSON.md"
}
],
"integration": {
"mandatory_for": [
"Multi-runtime compatibility issues",
"Module system deep dives",
"Tool/framework integration problems"
],
"workflow": [
"1. Stop before implementing any solution",
"2. Use Phase 1 (Characterization) checklist",
"3. Map all layers involved",
"4. Read source code of failure points",
"5. Create minimal reproduction",
"6. Design solution based on root cause",
"7. Document the why, not just the what"
]
},
"success_criteria": [
"Can explain root cause clearly",
"Solution addresses cause not symptoms",
"Predicted fix before implementing",
"Understand why other attempts failed",
"Can generalize to similar issues"
]
}