baekenough/stuck-recovery

Stuck Recovery Skill

Detects when tasks are stuck in repetitive failure loops and advises recovery strategies. Advisory-only — the orchestrator decides the action (R010).

Detection Signals

| Signal | Pattern | Threshold | |--------|---------|-----------| | Repeated error | Same error message appears 3+ times | 3 occurrences | | Edit loop | Same file edited 3+ times in sequence | 3 edits | | Agent retry | Same agent_type fails 3+ times consecutively | 3 failures | | Tool loop | Same tool called 5+ times with similar input | 5 calls |

Recovery Strategies

| Strategy | When | Action | |----------|------|--------| | Fresh context | Repeated same error | Suggest rephrasing the task | | Model escalation | Agent retry loop | Trigger model-escalation advisory | | Alternative approach | Edit loop detected | Suggest different file/method | | Human intervention | All automated strategies exhausted | Ask user for guidance | | Context reset | Long-running task (>30min) or context >80% | Structured handoff: save state to memory, create fresh session with task summary |

Architecture

PostToolUse (Edit, Write, Bash, Task) → stuck-detector.sh
  Tracks: tool_name, file_path, error_hash, agent_type
  Storage: /tmp/.claude-tool-history-$PPID (JSON lines, max 100)
  Detection: sliding window pattern matching
  Output: stderr advisory when loop detected

Advisory Format

--- [Stuck Detection] Loop detected ---
  Signal: {signal_type}
  Pattern: {description}
  Occurrences: {count}/{threshold}
  💡 Recovery: {suggested_strategy}
---

Integration

• Complements model-escalation skill (escalation is one recovery strategy)
• Respects R010 (advisory only, orchestrator decides)
• Uses same PPID-scoped temp file pattern as other hooks
• Works with task-outcome-recorder.sh data when available

Context Reset Strategy

For long-running tasks (>30 minutes) or when context usage exceeds 80%, context reset is preferred over compaction:

1. Save state: Write current progress, decisions, and open items to native auto-memory
2. Create handoff: Generate structured task summary with:
   • Completed steps and their outcomes
   • Current step and its state
   • Remaining steps
   • Key decisions made and their rationale
3. Reset: Start fresh session with handoff document as input

Context reset preserves decision quality by avoiding the information loss inherent in compaction. Based on Anthropic's finding that models experience "context anxiety" — prematurely concluding tasks due to perceived token limits.

When to Use

| Condition | Strategy | |-----------|----------| | Context < 60% | Continue normally | | Context 60-80% | Consider /compact | | Context > 80% OR duration > 30min | Context reset recommended | | Repeated compaction in same session | Context reset required |