| name | stuck |
| description | Detect when an agent is looping or failing repeatedly, and trigger structured recovery — backtrack, simplify, or escalate. |
Stuck Detection & Recovery
Symptoms
You are stuck if any of these are true:
- Same error message appeared 2+ times in a row
- You reverted the same change twice
- The metric hasn't improved in 3+ iterations
- You're making changes that don't address the actual error
- You're adding complexity to work around a problem instead of fixing it
Recovery Protocol
0. Check the Scratchpad
Read .devkit/scratchpads/current.md first. It records what was already tried and why it failed. If the scratchpad shows 3+ failed iterations, skip straight to Step 5: Escalate — the pattern of failures is the diagnosis.
1. Stop and Diagnose
Don't retry the same approach. Read the error carefully:
- What is the actual error message?
- What file and line does it point to?
- Is this the same error as last iteration, or a new one?
2. Backtrack
If the last 2+ attempts failed:
- Revert to the last known-good state:
git checkout -- .
- Re-read the original goal and the current state of the code
- The problem may be upstream of where you're looking
3. Simplify
Reduce scope:
- Fix one thing at a time, not three
- Remove the last thing you added and see if the base case works
- Use the simplest possible implementation, even if inelegant
4. Change Strategy
If the same approach failed twice:
- Try a fundamentally different approach, not a variation
- Read the docs or source of the library/API you're calling
- Check if the function signature or types changed
5. Escalate
If you've tried 3+ different approaches:
- Report what you've tried and what failed
- Show the exact error
- Ask the user for guidance — they may know something you don't
Anti-Patterns
- Retry loop — Running the same command hoping for a different result
- Shotgun debugging — Changing multiple things at once without understanding why
- Complexity spiral — Adding workarounds on top of workarounds
- Ignoring the error — Suppressing or catching exceptions instead of fixing the cause
