Stuck Detection

Stuck Detection Guard

Detect when an agent is repeating the same topics across turns and surface a self-reflection nudge so the orchestrator can break the loop. Lightweight, deterministic, no external services.

Triggers

Quick Reference

When to Use

Use this skill when:

• Building an orchestrator that risks repeating tool calls or status updates
• A long-running session shows degraded variety in responses
• You want a cheap pre-flight guard before sending a response

Use a richer evaluation instead when:

• You need semantic similarity (this uses lexical Jaccard only)
• You need multi-turn intent tracking
• You need cross-session coherence checks

How It Works

1. Topic signature. Strip stopwords, take the top N significant words by frequency, sort them, and join with commas. This is the response's signature.
2. History. Append each signature with a UTC timestamp to a JSON file. Keep only the most recent entries.
3. Jaccard similarity. Compare the current signature against the most recent K entries. Count how many exceed the similarity threshold.
4. Trigger. When K consecutive recent entries are similar, emit a nudge payload telling the orchestrator to ask the user a question or change topic.

Process

1. Run python3 .claude/skills/stuck-detection/stuck_detection.py check "<text>"
2. If the JSON result has "stuck": true, inject the nudge field into the orchestrator's next system prompt so the model self-corrects on its next turn. The nudge is internal control text wrapped in <stuck-detection> tags. Do not render it directly to the end user.
3. After a confirmed topic change, call reset to clear stale history.

Usage

# Check a response for stuck pattern (text via arg or stdin)
python3 .claude/skills/stuck-detection/stuck_detection.py check "your response text"
echo "your response" | python3 .claude/skills/stuck-detection/stuck_detection.py check

# Show current history state
python3 .claude/skills/stuck-detection/stuck_detection.py status

# Reset history after a topic change
python3 .claude/skills/stuck-detection/stuck_detection.py reset

# Extract signature only (debugging)
python3 .claude/skills/stuck-detection/stuck_detection.py extract "your text"

Output

{
  "stuck": true,
  "signature": "deploy,error,pipeline,retry,timeout",
  "similar_count": 3,
  "nudge": "<stuck-detection>\nSELF-REFLECTION: Loop detected.\n..."
}

Configuration

Defaults are conservative. Override at the function call site or via constants in stuck_detection.py:

History Path

Resolution order:

1. --history <path> CLI flag
2. STUCK_DETECTION_HISTORY environment variable (full path)
3. STUCK_DETECTION_SESSION environment variable (per-session file under the XDG state dir, e.g. history-<session>.json); use this when running multiple concurrent sessions to prevent cross-session contamination
4. $XDG_STATE_HOME/claude-stuck-detection/history.json
5. ~/.local/state/claude-stuck-detection/history.json

Paths are expanded and resolved before use. Avoid relative .. segments in --history or STUCK_DETECTION_HISTORY if you need the resolved location to match the input.

Verification

After integrating, confirm the following before relying on the guard:

• python3 .claude/skills/stuck-detection/stuck_detection.py status returns valid JSON with the configured history_length
• Three calls to check with the same long input return "stuck": true on the third call
• A call to reset zeroes history_length on the next status check
• The history file lives outside the repository working tree (XDG state dir or env-overridden path)
• Generated nudge text is forwarded into the orchestrator system prompt, not rendered to the end user
• Concurrent check calls never produce truncated JSON (atomic write via temp file + replace)
• A malformed history file (non-list, missing keys, non-string values) is treated as empty and not propagated to callers
• Tests in tests/skills/stuck-detection/ pass under uv run pytest

Anti-Patterns

Integration

Call from a hook or orchestrator wrapper. When stuck is true, prepend the nudge to the system prompt for the next turn so the model self-corrects.

Testing

uv run pytest tests/skills/stuck-detection/ -v