worker-stuck-protocol

name	worker-stuck-protocol
description	What to do when a worker agent gets stuck
disable-model-invocation	true

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