Cursor rule

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