/diagnose-stall

# story: e45s38
name: diagnose-stall
model: haiku
effort: light
description: 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.

Diagnose Stall

> **HARD GATE** — Do NOT restart work blindly. Run this diagnostic first when orchestration goes quiet without an explicit terminal state.

Explicit handler for silent stalls in long-running agent workflows (`/loop`, `dispatch-agents`, `execute-plan`, `build-epic` resume mode).

Stall signals

| Signal | Likely cause | |--------|----------------| | No stdout for >5 min on a monitored loop tick | Sleep/watcher misconfigured or prompt never re-armed | | Subagent dispatched but no completion message | Agent hung, blocked on approval, or scope too large | | `dispatch-agents` cycle 3 reached with gaps | Circuit exhausted — needs human escalation | | Verify command running >15 min | Missing timeout or waiting on external service | | `handoff.next_skill` unchanged across turns | Prior skill never wrote handoff |

Process

1. **Read state** — `specs/state.yaml`: `handoff.next_skill`, `active_flow`, `metrics.story_start`, open decisions. 2. **Check locks** — `bash scripts/check-stale-locks.sh` if present; read `specs/agent-locks.yaml`. 3. **Inspect terminals** — list background shells; note PIDs, last output timestamp, exit codes. 4. **Classify stall type:**

• **waiting_approval** — tool blocked on user consent
• **blocked_dependency** — prior task incomplete or red gate
• **agent_exhausted** — max iterations/cycles reached
• **misconfigured_loop** — duplicate sentinel, wrong regex, or sleeper not re-armed
• **external_io** — network, CI, or deploy wait without timeout
• **unknown** — escalate with evidence bundle

5. **Recommend recovery** — one action only (resume, kill PID, re-dispatch with smaller brief, escalate to user). 6. **Write report** — `specs/verifications/STALL-<timestamp>.md` with classification, evidence, and recommended next skill.

Integration

| Caller | When to invoke | |--------|----------------| | `/loop` (Cursor) | After two consecutive ticks with no observable progress | | `dispatch-agents` | When a wave exceeds expected duration with zero returns | | `execute-plan` | When a step checkpoint is overdue | | User | "Why did this stop?" / "Nothing is happening" |

Verify

→ verify: `test -f specs/state.yaml`

Handoff

Gate: READY → next: survey-context (if state unclear) or resume prior skill from `state.yaml` Writes: `specs/verifications/STALL-*.md`