---
name: Diagnose Stall
slug: diagnose-stall
category: Automation
description: Diagnose Stall identifies why agent orchestration stopped making progress in loops, dispatches, or plan execution. Use it when output goes quiet, a subagent never returns, or a checkpoint is overdue.
github: "https://github.com/danielvm-git/bigpowers/tree/main/skills/diagnose-stall"
language: Shell
stars: 173
forks: 14
install: "npx degit https://github.com/danielvm-git/bigpowers/tree/main/skills/diagnose-stall ~/.claude/skills/diagnose-stall"
installs_to: ~/.claude/skills/diagnose-stall
source_path: skills/diagnose-stall/SKILL.md
collection_size: 23
category_size: 2109
collection_url: "https://dirskills.com/collections/danielvm-git/bigpowers"
added: 2026-09-07T05:22:14.046Z
last_synced: 2026-09-07T05:22:14.046Z
canonical_url: "https://dirskills.com/skills/diagnose-stall"
---

# Diagnose Stall

Diagnose Stall identifies why agent orchestration stopped making progress in loops, dispatches, or plan execution. Use it when output goes quiet, a subagent never returns, or a checkpoint is overdue.

**Install:**

```bash
npx degit https://github.com/danielvm-git/bigpowers/tree/main/skills/diagnose-stall ~/.claude/skills/diagnose-stall
```

## README

# 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`