Run tasks in a loop until goals are met — use for iterative refinement, polling, or convergence
69%
Does it follow best practices?
Run evals on this skill
Adds up to 20 points to the overall score
Passed
No findings from the security scan
Fix and improve this skill with Tessl
tessl review fix ./.claude/skills/skill-iterative-loop/SKILL.mdSystematic iterative execution with clear goals, exit conditions, and progress tracking.
Core principle: Define goal → Set max iterations → Execute → Evaluate → Loop or complete.
Use this skill when user wants to:
Do NOT use for:
**Loop Intent:**
Goal: [what should be achieved]
Success criteria: [how do we know we're done]
Max iterations: [safety limit]
Per-iteration tasks: [what to do each loop]Use AskUserQuestion if unclear:
**Safety Validation:**
- [ ] Max iterations defined (no infinite loops)
- [ ] Success condition is measurable
- [ ] Each iteration makes progress
- [ ] Failure exit strategy exists
- [ ] User aware of potential durationNever proceed without max iterations defined.
**Starting Iterative Loop**
Goal: [description]
Max iterations: [N]
Success criteria: [condition]
---
### Iteration 1 / [N]For each iteration:
**Iteration [current] / [max]**
**Actions:**
1. [Action 1]
→ [result/output]
2. [Action 2]
→ [result/output]
3. [Action 3]
→ [result/output]
**Evaluation:**
- Success criteria met? [Yes/No]
- Progress made? [Yes/No]
- Issues found: [list any issues]
**Status:** [Continue/Success/Need intervention]
---Use TodoWrite to track iterations:
Iteration Progress:
✓ Iteration 1 - [what was done]
✓ Iteration 2 - [what was done]
⚙️ Iteration 3 - [in progress]
- Iteration 4 - [pending]
- Iteration 5 - [pending]🎉 **Success! Loop complete.**
**Goal achieved:** [description]
**Iterations used:** [N] / [max]
**Final state:**
[description of what was achieved]
**Summary of iterations:**
1. Iteration 1: [what happened]
2. Iteration 2: [what happened]
...
N. Iteration N: [what happened] ✓ Success⚠️ **Max iterations reached without full success**
**Iterations completed:** [max]
**Goal:** [description]
**Current state:** [how close we got]
**Progress made:**
- [Improvement 1]
- [Improvement 2]
- [Improvement 3]
**Remaining issues:**
- [Issue 1]
- [Issue 2]
**Options:**
1. Accept current state (substantial progress made)
2. Continue with [N] more iterations
3. Change approach (current method may not work)
What would you like to do?🛑 **Stopping early: No progress detected**
**Iteration:** [N] / [max]
**Reason:** Last [M] iterations showed no improvement
**Analysis:**
This suggests the current approach may be fundamentally flawed.
**Recommendation:**
Rather than continue looping, let's:
1. Analyze why no progress is being made
2. Consider alternative approaches
3. Re-evaluate the goal or success criteria
Shall we pause and reassess?User: "Loop around 5 times auditing, enhancing, testing, until it's done"
Implementation:
**Loop Goal:** Code passes all quality gates
**Max Iterations:** 5
**Per-iteration:**
1. Audit code for issues
2. Enhance/fix identified issues
3. Run tests
4. Check if all pass
**Success:** All tests pass + no issues found
Execute:
Iteration 1:
- Audit → Found 8 issues
- Fix → Fixed 8 issues
- Test → 2 tests still failing
- Continue
Iteration 2:
- Audit → Found 2 new issues from fixes
- Fix → Fixed 2 issues
- Test → All tests pass ✓
- Success! Stopping early (2/5 iterations used)User: "Keep trying optimizations until we hit < 100ms response time"
Implementation:
**Loop Goal:** Response time < 100ms
**Max Iterations:** 10
**Per-iteration:**
1. Measure current performance
2. Identify bottleneck
3. Apply optimization
4. Re-measure
**Success:** Response time < 100ms
Execute:
Iteration 1: 450ms → Cache database queries → 280ms (Continue)
Iteration 2: 280ms → Add index to frequent query → 150ms (Continue)
Iteration 3: 150ms → Implement response compression → 85ms (Success!)User: "Try deploying, retry up to 3 times if it fails"
Implementation:
**Loop Goal:** Successful deployment
**Max Iterations:** 3
**Per-iteration:**
1. Attempt deployment
2. Check status
3. If failed, wait before retry
**Success:** Deployment succeeds
Execute:
Iteration 1: Deploy → Failed (API timeout) → Wait 10s
Iteration 2: Deploy → Failed (API timeout) → Wait 20s
Iteration 3: Deploy → Success ✓User: "Iterate 4 times improving the error messages based on user feedback"
Implementation:
**Loop Goal:** Error messages meet clarity standard
**Max Iterations:** 4
**Per-iteration:**
1. Review current error messages
2. Identify confusing ones
3. Rewrite for clarity
4. Evaluate against criteria
**Success:** All messages rated 8+/10 for clarity
Execute each iteration with progressive improvementLoop for debugging:
"Keep debugging until all tests pass, max 5 tries"
Each iteration:
- Use skill-debug to investigate failure
- Apply fix
- Re-run tests
- EvaluateLoop for comprehensive checking:
"Loop 3 times auditing different aspects"
Iteration 1: Audit security
Iteration 2: Audit performance
Iteration 3: Audit accessibilityLoop for TDD cycles:
"Do 5 red-green-refactor cycles"
Each iteration:
- Write failing test (red)
- Make it pass (green)
- Refactor (refactor)
- Evaluate and continueGood:
Loop max 5 times trying to fix the issueDangerous:
Keep trying until it works
(What if it never works? Infinite loop!)Good:
Success: All 15 tests pass AND code coverage > 80%Poor:
Success: Code looks better
(Too subjective)**Progress Tracking:**
Iteration 1: 5/15 tests passing
Iteration 2: 10/15 tests passing
Iteration 3: 13/15 tests passing
Iteration 4: 15/15 tests passing ✓Don't continue looping if goal is achieved:
**Iteration 2/5:** All tests pass!
Stopping early - goal achieved.
No need to continue to iteration 3.Iteration 4: 10/15 tests passing
Iteration 5: 10/15 tests passing
Iteration 6: 10/15 tests passing
⚠️ No progress in 3 iterations - stopping to reassess approach| Action | Why It's Dangerous |
|---|---|
| No max iterations | Could loop forever |
| Vague success criteria | Don't know when to stop |
| No progress tracking | Can't tell if making progress |
| Ignoring stalls | Waste time on ineffective approach |
| Same action each loop | If not working, need different approach |
If the strategy-rotation hook fires, immediately change approach. Do not retry the same approach. Explain what you'll do differently before the next attempt. The hook fires after consecutive failures of the same tool — this is a strong signal that the current approach is fundamentally wrong, not just slightly off.
Every iterative loop MUST track a Self-Regulation Score that accumulates danger signals. This prevents runaway loops where the agent keeps "fixing" things without real progress.
Maintain a mental window of the last 10 iterations (or fewer if less than 10 have run). After each iteration, check for repeated patterns:
Single-state repetition: Did the same outcome/error occur 3+ times consecutively?
Multi-step cycle detection: Is there an A→B→A→B oscillation?
On first detection: Announce the pattern to the user. Attempt ONE diagnostic retry with explicit acknowledgment: "This pattern has repeated — here's what I'll do differently: [specific change]."
On second detection: HALT immediately. Display the detected cycle and ask the user whether to continue with a completely different approach or stop.
Track a cumulative score starting at 0%. Each event adds to the score.
Default weights (override via ~/.claude-octopus/loop-config.conf):
| Event | Score Impact |
|---|---|
| Revert (git revert, undo, roll back) | +15% |
| Touching files unrelated to the stated goal | +20% |
| A fix that requires changing >3 files | +5% |
| After the 15th fix attempt | +1% per additional fix |
| All remaining issues are Low severity | +10% |
If WTF score exceeds 20%: STOP immediately. Show:
Hard cap: 50 iterations regardless of score or progress. No exceptions.
At loop start, check for ~/.claude-octopus/loop-config.conf. If it exists, read the key=value pairs and use them instead of defaults. Format:
# Loop Self-Regulation Configuration
WINDOW_SIZE=10
REVERT_PENALTY=15
UNRELATED_FILES_PENALTY=20
LARGE_FIX_PENALTY=5
AFTER_FIX_15_PENALTY=1
ALL_LOW_SEVERITY_PENALTY=10
WTF_THRESHOLD=20
HARD_CAP=50
STUCK_THRESHOLD=3If the file does not exist, use the defaults shown above. Users can create this file to tune sensitivity for their workflow.
You do NOT need external tools for this. Track mentally during the loop:
Iteration 5/20 | Self-regulation: 10% (1 revert, 0 unrelated files)The strategy-rotation hook and self-regulation are complementary:
For metric runs, Metric Verification Mode replaces the general iteration limits and 30-minute continue prompt below. Its stop budgets cannot be extended by a checkpoint. Self-regulation revert counters do not apply because metric runs forbid reverts in the original workspace.
MAX_ITERATIONS = user_specified or 10 # Always have a limit
HARD_CAP = 50 # Absolute maximum regardless of user settingTrack WTF score across iterations.
If score > 20%: STOP and ask user.Track last 10 iterations.
If repeated pattern detected twice: STOP and ask user.If last 3 iterations show same result:
→ Stop and ask userIf total time > 30 minutes:
→ Checkpoint progress
→ Ask user if should continueEvery N iterations:
→ Show progress
→ Ask if should continue or adjust approach| Pattern | Max Iterations | Success Criteria | Early Exit |
|---|---|---|---|
| Test until pass | 5-10 | All tests pass | Yes |
| Performance optimization | 10-20 | Metric < target | Yes |
| Retry with backoff | 3-5 | Operation succeeds | Yes |
| Incremental refinement | 3-7 | Quality threshold met | Maybe |
| Comprehensive audit | 3-5 | All areas covered | No |
When the user supplies Metric: <command>, use mechanical measurement in a
bounded candidate-copy experiment. Without a metric, use the normal loop above.
Freeze the metric, direction, guard, and authorized editable paths before the
baseline. The guard is optional. Without a guard, accept only a measured
improvement and report that no guard ran; do not claim safety validation.
Defaults are five iterations, 30 elapsed minutes, and 14 additional
model calls. Iterations: N accepts integers 1 through 20. Minutes: N and
Calls: N accept positive integers. Explicit choices replace those defaults;
invalid options stop before edits or calls. Stop at the first exhausted budget
or after two rounds without measured improvement. Metric and guard subprocesses
must have deadlines no longer than the remaining elapsed budget. If the host
cannot enforce a subprocess deadline, report the missing capability and stop.
Charge retries, research, and model-assisted edits to the call budget before
dispatch. Never reset elapsed time or consumed calls on resume.
| Parameter | Meaning |
|---|---|
Metric: <command> | Must print one finite number |
Direction: higher or Direction: lower | Select the improving direction |
Guard: <command> | Optional. When supplied, must exit zero to accept a candidate |
Iterations: N, Minutes: N, Calls: N | Override the finite defaults above |
Inspect repository status, including the staged index, dirty tracked files, and untracked files. Snapshot the exact authorized input bytes and their hashes. Create a unique private run directory outside the working repository, with separate original, best, and candidate copies. Never operate on unrelated paths. If the metric needs the whole repository, create a disposable isolated copy containing the required authorized baseline, including relevant existing edits. Do not silently substitute HEAD for a dirty baseline. If the host cannot create that faithful isolated baseline without exposing unrelated data, stop and name the limitation. Reject symlinks that would let experiments modify original files.
Do not stage, commit, stash, reset, clean, or revert the user's repository as part of an experiment. In particular, never use blanket staging. Git history is not the experiment store. Preserve the original index exactly.
iterations.jsonl.Before publishing the best candidate, re-read every destination and verify it still matches the snapshot taken at the start. Also verify the repository HEAD and index have not changed. On a concurrent edit or index change, stop and preserve the candidate for review. Publish only the exact authorized files, then rerun the required checks against delivered bytes. Do not create a commit unless the user separately requested one.
Example ledger record, with paths and hashes referring only to this run:
{"iteration":1,"timestamp":"2026-11-07T12:00:00Z","metric":72.5,"best":72.5,"status":"kept","description":"One measured change","artifact_sha256":"<candidate hash>","elapsed_seconds":45,"calls_used":1}Use kept, rejected, or error for attempted rounds. Preserve rejected
candidate evidence and failed guard outputs without changing the original.
Resume only from the explicitly selected run directory, never from a shared per-day log. Verify its artifact hashes, frozen metric and guard, limits, elapsed start time, consumed calls, best candidate, and publication state. A changed contract requires a new baseline within the remaining budget. If elapsed budget expired while interrupted, report that stop without dispatch. Report baseline and each attempted round, actual checks, accepted/rejected changes, consumption, delivered hashes, and the stop reason. Unknown monetary cost stays unknown. These are host-managed steps, not an executable supervisor.
Iterative loop → Clear goal + Max iterations + Progress tracking + Exit strategy
Otherwise → Infinite loops + Wasted effort + Unclear when doneDefine the goal. Set the limit. Track progress. Know when to stop.
nyldn/claude-octopus
9a6967a
If you maintain this skill, you can claim it as your own. Once claimed, you can manage eval scenarios, bundle related skills, attach documentation or rules, and ensure cross-agent compatibility.