# Iterating To Completion

> Prevents premature exit and infinite loops. Three mechanisms: Completion Promises, Scratchpads, Loop Detection.

- Skill: `mayarid/iterating-to-completion` (Agent Skill)
- Install (CLI): `npx skillmds@latest add mayarid/iterating-to-completion`
- Raw SKILL.md: https://api.skillmd.com/api/skills/mayarid/iterating-to-completion/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: mayarid (https://skillmd.com/u/mayarid)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/mayarid/iterating-to-completion

---


## Purpose

This skill prevents two failure modes:
1. **Premature exit** — agent stops before success criteria are met
2. **Infinite loop** — agent spins endlessly with no progress

## Mechanism 1: Completion Promises

Every agent task has an explicit completion signal. The agent outputs this string ONLY when success criteria are truly met:

| Role | Signal | Meaning |
|---|---|---|
| Lead | `ARCHITECTURE_PLAN_COMPLETE` | Architecture JSON is complete and valid |
| Developer | `IMPLEMENTATION_COMPLETE` | Code compiles, lints pass, basic sanity checked |
| Reviewer | `REVIEW_COMPLETE` | Review report generated (approved or rejected) |
| Test Lead | `TEST_PLAN_COMPLETE` | Test plan JSON is complete |
| Tester | `ALL_TESTS_PASSING` | All tests pass, coverage met |

**Rule:** Never output the completion signal unless the criteria are truly met. The orchestrator blocks on this signal.

## Mechanism 2: Scratchpad Protocol

Maintain a scratchpad file at `.jonggrang/.ephemeral/scratchpad-{task_id}.md`:

```markdown
# Task: {task_id} — {title}
## Completed Steps
- [x] Step 1 — what was done
- [x] Step 2 — outcome

## Current Focus
- [ ] Step 3 — what you're working on now

## Failures & Learnings
- Attempt 2: Failed because X. Will try Y instead.

## Next Step
Clear description of what you do next iteration.
```

Update this EVERY iteration. If you're stuck, the scratchpad shows why.

## Mechanism 3: Loop Detection

The orchestrator reads your last 3 outputs. If similarity > 90%, you're stuck.

**Signs you're stuck:**
- Repeating the same command outputs
- The same error message appearing 3+ times
- Trying the same approach with minor variation

**When stuck:**
1. Write to scratchpad: "STUCK: [reason]"
2. Try a fundamentally different approach (not a variation)
3. If still stuck after 2 more tries, output `BLOCKED: [reason]` and stop

## Iteration Limit

Max 10 iterations per agent spawn. After 10:
1. Write current state to scratchpad
2. Output `ITERATION_LIMIT_REACHED: [what's left]`
3. Orchestrator will re-spawn you with fresh context and the scratchpad

## Integration with Hooks

The `feedback-loop.sh` / OpenCode `session.idle` hook enforces this:
- If dirty bit is set and you output a completion signal without going through reviewer/tester, the hook blocks your exit.
- You must demonstrate the full cycle: implement → review → test → signal.