Architectural Upgrade 2026-03-30: Modular Emacs, org-gtd v4.0, and PSF Phase 1

notes/tool-failure-protocol.org

@@ -0,0 +1,53 @@
+#+TITLE: Tool Failure Protocol
+#+AUTHOR: User
+#+CREATED: [2026-03-17 Mon]
+#+ID: 20260317-tool-failure-protocol
+#+BEGIN_COMMENT
+When encountering tool errors, follow debug protocol instead of panic responses.
+#+END_COMMENT
+
+* The Protocol
+
+When tools fail, execute these steps in order:
+
+1. READ the error message completely
+2. IDENTIFY the specific issue (missing parameter? syntax error? wrong path?)
+3. FIX the actual syntax problem
+4. RETRY with corrected parameters
+5. ESCALATE only if 2 attempts fail — with SPECIFIC error, not "what should I do?"
+
+* Anti-Patterns (STOP DOING)
+
+** Gateway Restart Misuse
+Using gateway restart as panic response to tool errors is WRONG because:
+- Restarts are for gateway service issues, not syntax errors
+- Doesn't fix the underlying problem
+- Disrupts service unnecessarily
+
+** When to ACTUALLY restart gateway:**
+- Gateway daemon unresponsive (not heartbeat check)
+- Actual service crashes or memory leaks
+- NOT for: tool syntax errors, model timeouts, context saturation
+
+** Decision Escalation
+Asking "What should I do?" when I have:
+- Complexity check results
+- Clear criteria for action
+- SOUL.md mandate for "No Operational Escalation"
+
+* Positive Patterns to Reinforce
+
+** Work Breakdown Success
+Identified 51 gaps across 10 files as complex.
+Decomposed into atomic tasks.
+Used sub-agents for parallel execution.
+Results: efficient verification with proper orchestration.
+
+** Wait Mode Discipline
+After spawning sub-agents, entered proper wait mode.
+Did NOT poll status or restart gateway.
+Waited for push-based completion events.
+
+* Core Rule
+
+Tool failure is a debug challenge, not a crisis.