From 297adf842508ae5ebcc556d18cc81785def17a06 Mon Sep 17 00:00:00 2001
From: Tom Boucher <trekkie@nomorestars.com>
Date: Wed, 18 Mar 2026 17:13:55 -0400
Subject: [PATCH] fix: add Windows troubleshooting for plan-phase freezes
 (#732)

Windows users experience plan-phase freezes due to Claude Code stdio
deadlocks with MCP servers. When a subagent hangs, the orchestrator
blocks indefinitely with no timeout or error.

Adds:
- Windows troubleshooting section to plan-phase.md with:
  - Orphaned process cleanup (PowerShell commands)
  - Stale task directory cleanup (~/.claude/tasks/)
  - MCP server reduction advice
  - --skip-research fallback to reduce agent chain
- Stale task directory detection to health.md (I002 diagnostic)
  - Reports count of stale dirs on --repair
  - Safe cleanup guidance

Closes #732
---
 get-shit-done/workflows/health.md     | 22 ++++++++++++++++++++++
 get-shit-done/workflows/plan-phase.md | 24 ++++++++++++++++++++++++
 2 files changed, 46 insertions(+)

diff --git a/get-shit-done/workflows/health.md b/get-shit-done/workflows/health.md
index 54b7a1423..0cb95fd1b 100644
--- a/get-shit-done/workflows/health.md
+++ b/get-shit-done/workflows/health.md
@@ -157,3 +157,25 @@ Report final status.
 - Orphaned plan cleanup
 
 </repair_actions>
+
+<stale_task_cleanup>
+**Windows-specific:** Check for stale Claude Code task directories that accumulate on crash/freeze.
+These are left behind when subagents are force-killed and consume disk space.
+
+When `--repair` is active, detect and clean up:
+
+```bash
+# Check for stale task directories (older than 24 hours)
+TASKS_DIR="$HOME/.claude/tasks"
+if [ -d "$TASKS_DIR" ]; then
+  STALE_COUNT=$(find "$TASKS_DIR" -maxdepth 1 -type d -mtime +1 2>/dev/null | wc -l)
+  if [ "$STALE_COUNT" -gt 0 ]; then
+    echo "⚠️  Found $STALE_COUNT stale task directories in ~/.claude/tasks/"
+    echo "   These are leftover from crashed subagent sessions."
+    echo "   Run: rm -rf ~/.claude/tasks/*  (safe — only affects dead sessions)"
+  fi
+fi
+```
+
+Report as info diagnostic: `I002 | info | Stale subagent task directories found | Yes (--repair removes them)`
+</stale_task_cleanup>
diff --git a/get-shit-done/workflows/plan-phase.md b/get-shit-done/workflows/plan-phase.md
index 2d3291533..26697dc3e 100644
--- a/get-shit-done/workflows/plan-phase.md
+++ b/get-shit-done/workflows/plan-phase.md
@@ -737,6 +737,30 @@ Verification: {Passed | Passed with override | Skipped}
 ───────────────────────────────────────────────────────────────
 </offer_next>
 
+<windows_troubleshooting>
+**Windows users:** If plan-phase freezes during agent spawning (common on Windows due to
+stdio deadlocks with MCP servers — see Claude Code issue anthropics/claude-code#28126):
+
+1. **Force-kill:** Close the terminal (Ctrl+C may not work)
+2. **Clean up orphaned processes:**
+   ```powershell
+   # Kill orphaned node processes from stale MCP servers
+   Get-Process node -ErrorAction SilentlyContinue | Where-Object {$_.StartTime -lt (Get-Date).AddHours(-1)} | Stop-Process -Force
+   ```
+3. **Clean up stale task directories:**
+   ```powershell
+   # Remove stale subagent task dirs (Claude Code never cleans these on crash)
+   Remove-Item -Recurse -Force "$env:USERPROFILE\.claude\tasks\*" -ErrorAction SilentlyContinue
+   ```
+4. **Reduce MCP server count:** Temporarily disable non-essential MCP servers in settings.json
+5. **Retry:** Restart Claude Code and run `/gsd:plan-phase` again
+
+If freezes persist, try `--skip-research` to reduce the agent chain from 3 to 2 agents:
+```
+/gsd:plan-phase N --skip-research
+```
+</windows_troubleshooting>
+
 <success_criteria>
 - [ ] .planning/ directory validated
 - [ ] Phase validated against roadmap