# Worker Stuck Protocol

> What to do when a worker agent gets stuck

- Skill: `eron1703/worker-stuck-protocol` (Agent Skill)
- Install (CLI): `npx skillmds@latest add eron1703/worker-stuck-protocol`
- Raw SKILL.md: https://api.skillmd.com/api/skills/eron1703/worker-stuck-protocol/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: eron1703 (https://skillmd.com/u/eron1703)
- Updated: 2026-09-10
- Page: https://skillmd.com/skills/eron1703/worker-stuck-protocol

---


# Worker Stuck Protocol

## When Are You Stuck?

You are stuck if ANY of these are true:
- 3 consecutive tool calls without measurable progress toward your task
- An SSH command times out or returns permission denied
- A Git push/pull fails with authentication errors
- A required service, file, or endpoint doesn't exist where expected
- You're guessing at URLs, paths, or credentials instead of knowing them

## What To Do When Stuck

### Step 1: STOP immediately
Do not try another approach. Do not explore. Do not guess.

### Step 2: Diagnose — is this a missing capability or a real blocker?

**Missing capability** = you need facts from a skill you don't have (DB connection string, service ports, K8S namespace).
→ Use `NEED_CAPABILITY` pattern (see worker-role skill). The supervisor can grant you the knowledge skill.

**Real blocker** = you have the facts but something is wrong (service down, permission denied, unexpected error).
→ Use `BLOCKED` + `QUESTIONS` pattern below.

### Step 3: Report and exit
Use the `worker-reporting` format with STATUS: BLOCKED.

For capability requests, include `NEED_CAPABILITY` section (see worker-reporting skill).

For other blockers, include `QUESTIONS` section. Be SPECIFIC:
- BAD: "I need access to the repo"
- GOOD: "Git push to gitlab.com/flow-master/scheduling failed with 401. I need a valid GitLab PAT with write access to this repo."

- BAD: "The service doesn't work"
- GOOD: "GET http://localhost:9003/api/v1/processes/ returns 400 Bad Request. I need to know the correct route path for listing processes in the process-design service."

### Step 4: Include what you learned
Even if you're blocked, you may have gathered useful information. Include it:
- Error messages (exact text)
- What routes/endpoints DO work
- What files you found
- What environment variables are set

## Key Principle
**Your time is expensive. The supervisor can resume you with better context in seconds. Wasting 10 minutes exploring is worse than exiting in 30 seconds with a clear question.**

## Anti-Patterns (NEVER DO THESE)
- Trying 10 different URL patterns hoping one works
- Running the same failing command with slight variations
- Searching the entire filesystem for a file that should be in your skill files
- Attempting to authenticate with different credential combinations
- Spending more than 2 minutes on ANY single problem without progress