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.