toolsets/stuck-toolkit/doc.md

stuck

---

name: stuck description: Help the agent and user get unstuck when progress has stalled — repeated failures, circular reasoning, unclear next steps, or confusion about what to do. Use when the agent is stuck in a loop, repeatedly failing, or the user expresses frustration about lack of progress.

Stuck — Troubleshooting Agent

When the agent or user is stuck, use this protocol to get back on track.

Recognize Being Stuck

Signs you're stuck:

• You've tried the same approach 3+ times without success
• You're going in circles (reading the same files, asking the same questions)
• The user expresses frustration
• You've been working for a long time without clear progress
• You're uncertain what to do next

Get Unstuck — Protocol

1. Stop and Acknowledge

Stop what you're doing. Acknowledge to the user that things aren't progressing. Be specific about what seems to be going wrong.

2. Diagnose the Problem

Ask yourself:

• What exactly am I trying to accomplish?
• What have I tried so far and what happened each time?
• Is the problem a tool limitation, a misunderstanding, missing information, or something else?
• Am I making unwarranted assumptions?

3. Change Approach

Pick one:

• Try a different tool or method: If tool A keeps failing, try tool B
• Break it down: Split the task into smaller, independently verifiable steps
• Simplify: Reduce scope to the minimal version of the problem
• Ask the user differently: Rephrase your question more clearly
• Research: Look up documentation, search for similar problems
• Start fresh: Clear your assumptions and approach from a blank slate
• Ask for help: Explicitly ask the user for guidance

4. Communicate

Tell the user:

• What you think the problem is
• What you plan to try differently
• What you need from them (if anything)

5. Execute the New Approach

Try exactly ONE new approach. Don't try multiple things at once. If it works, great. If not, go back to step 3.

Guidelines

• Don't keep doing the same thing. If it didn't work the first two times, it won't work the third.
• Explain your reasoning. The user can't help if they don't know what you're thinking.
• Be humble. Admit when you don't know something or when an approach failed.
• The simplest solution is often correct. Before reaching for complex solutions, check if a simpler approach works.