| name | loop-detection |
| description | Use when an agent is stuck editing the same file repeatedly without converging, or when verification requires doom loop analysis. |
| when_to_use | [feedback] Triggered after multiple unsuccessful edits to the same file or when verification detects repeated changes without progress. |
Loop Detection
Overview
Editing the same file repeatedly without convergence is a doom loop. Stop. Detect. Recover.
Core principle: Three edits to the same file without measurable progress = stop and reassess.
When to Use
- Edited same file 3+ times, problem persists
- Each edit fixes one thing, breaks another
- "Iterating" with no convergence evidence
- verification-before-completion detects repeated changes
Not for: Intentional multi-file refactors, systematic changes across different files, semantic/dialogue loops (those go to brainstorming's circuit-breaker — see Semantic Loop Detection section below).
Core Pattern
BEFORE each edit to a file you have already modified this session:
1. TRACK: bash scripts/loop-detector.sh --track <file>
2. CHECK: bash scripts/loop-detector.sh
3. ACT based on exit code:
0 = OK -> proceed
1 = WARNING -> reconsider approach (see Recovery)
2 = HARD STOP -> stop editing, mandatory recovery
Quick Reference
| Exit Code | Label | Threshold | Action |
|---|
| 0 | OK | <5 edits | Proceed, track edits |
| 1 | WARNING | >=5 edits | Reconsider, try different approach |
| 2 | HARD STOP | >=8 edits | Stop. Mandatory recovery. No more edits to this file. |
Thresholds configurable via env: LOOP_WARN_THRESHOLD, LOOP_HARD_THRESHOLD
Reset after successful approach change: bash scripts/loop-detector.sh --reset
Recovery Strategies
WARNING (exit 1) -- Reconsider
- Stop and re-read the original error/problem statement
- Check: am I treating symptoms instead of root cause?
- Try a different approach: different file, different strategy, different abstraction level
- If new approach works, reset tracker and continue
HARD STOP (exit 2) -- Mandatory Recovery
You MUST do ONE of the following before touching that file again:
- Rollback:
git checkout -- <file> and start fresh with a different plan
- Seek help: Ask your human partner for guidance, show them what you tried
- Replan: Step back, write a new plan, get it reviewed before implementing
No exceptions. HARD STOP means stop.
Semantic Loop Detection (issue #81)
Semantic loops (3+ consecutive no-tool turns with user rejecting proposals,
or 2+ active plans stacking in one session) are handled by the
brainstorming skill's circuit-breaker, not by this skill. loop-detection
focuses on the file-edit loop pattern (its script scripts/loop-detector.sh
tracks file edits, not dialogue turns).
If you observe a semantic-loop pattern and brainstorming is not active,
invoke agent-harness:brainstorming (it carries the clarification-loop
circuit-breaker) or recommend /compact + fresh session. See
skills/brainstorming/SKILL.md for the authoritative recovery rules.
触发诊断（不自动修复）： HARD STOP 时除原警告外，额外生成一份失败诊断报告，便于后续追溯同类循环：
scripts/diagnose-failure.sh --type loop --context '{"file":"<path>","edits":<n>}' --spec-topic "$SPEC_TOPIC"
诊断报告路径会输出到 stdout，status 信息输出到 stderr。报告只记录，不执行修复——由人审决定下一步。
Red Flags -- STOP Editing
- "This time is different" -- convergence evidence or stop
- "I'm iterating, not looping" -- iteration has measurable progress
- "Just one more fix" -- you said that last time
- "The user is waiting" -- looping wastes MORE time than stopping
- "I'm making progress" -- name the specific metric that improved
- "Each edit is small" -- small edits that don't converge = still a loop
- "I almost have it" -- "almost" for 5+ edits means no
- "The fix is more complex than expected" -- then replan
- "I need to try one more thing" -- after 5 attempts, trying isn't solving
If you recognize yourself above, stop and run loop-detector.sh.
Common Mistakes
| Mistake | Fix |
|---|
| Editing without tracking | Always --track before editing |
| Ignoring WARNING | WARNING exists to prevent HARD STOP |
| Resetting tracker without changing approach | Reset only after you have a genuinely new plan |
| Treating "different error" as progress | Same file, same root cause = still looping |
| Skipping detection "because I know I'm fine" | That confidence is the loop talking |
Rationalization Table
| Excuse | Reality |
|---|
| "I'm iterating, not looping" | Iteration converges. Where is your evidence? |
| "This time is different" | Prove it with a measurable outcome before editing |
| "Just one more small change" | You said that 5 times already |
| "User is waiting, no time to stop" | 8 failed edits waste more time than 1 reset |
| "I can see the end" | If you could, you would have finished by now |
| "The skill doesn't apply here" | That is the loop talking |
| "I'm making incremental progress" | Name the metric. No metric = no progress. |
| "This is a special case" | Every loop thinks it is special |
TDD Baseline (RED Phase)
Pressure scenario: agent fixing TypeScript error, 6 failed edits to same file, time pressure.
Baseline failures: agent continues without reflection, rationalizes "this time is different", does not call loop-detector.sh, does not consider alternatives.
