Windsurf rules

1---
2name: diagnose-stall
3model: haiku
4description: "Diagnose why agent orchestration stopped producing progress — silent stalls in /loop, dispatch-agents, or execute-plan. Use when work appears hung, no output for several minutes, or a subagent never returned."
5---
6 
7# Diagnose Stall
8 
9> **HARD GATE** — Do NOT restart work blindly. Run this diagnostic first when orchestration goes quiet without an explicit terminal state.
10 
11Explicit handler for silent stalls in long-running agent workflows (`/loop`, `dispatch-agents`, `execute-plan`, `build-epic` resume mode).
12 
13## Stall signals
14 
15| Signal | Likely cause |
16|--------|----------------|
17| No stdout for >5 min on a monitored loop tick | Sleep/watcher misconfigured or prompt never re-armed |
18| Subagent dispatched but no completion message | Agent hung, blocked on approval, or scope too large |
19| `dispatch-agents` cycle 3 reached with gaps | Circuit exhausted — needs human escalation |
20| Verify command running >15 min | Missing timeout or waiting on external service |
21| `handoff.next_skill` unchanged across turns | Prior skill never wrote handoff |
22 
23## Process
24 
251. **Read state** — `specs/state.yaml`: `handoff.next_skill`, `active_flow`, `metrics.story_start`, open decisions.
262. **Check locks** — `bash scripts/check-stale-locks.sh` if present; read `specs/agent-locks.yaml`.
273. **Inspect terminals** — list background shells; note PIDs, last output timestamp, exit codes.
284. **Classify stall type:**
29   - **waiting_approval** — tool blocked on user consent
30   - **blocked_dependency** — prior task incomplete or red gate
31   - **agent_exhausted** — max iterations/cycles reached
32   - **misconfigured_loop** — duplicate sentinel, wrong regex, or sleeper not re-armed
33   - **external_io** — network, CI, or deploy wait without timeout
34   - **unknown** — escalate with evidence bundle
355. **Recommend recovery** — one action only (resume, kill PID, re-dispatch with smaller brief, escalate to user).
366. **Write report** — `specs/verifications/STALL-<timestamp>.md` with classification, evidence, and recommended next skill.
37 
38## Integration
39 
40| Caller | When to invoke |
41|--------|----------------|
42| `/loop` (Cursor) | After two consecutive ticks with no observable progress |
43| `dispatch-agents` | When a wave exceeds expected duration with zero returns |
44| `execute-plan` | When a step checkpoint is overdue |
45| User | "Why did this stop?" / "Nothing is happening" |
46 
47## Verify
48 
49→ verify: `test -f specs/state.yaml`
50 
51## Handoff
52 
53Gate: READY → next: survey-context (if state unclear) or resume prior skill from `state.yaml`
54Writes: `specs/verifications/STALL-*.md`
55