# Iterate

> Autonomous multi-cycle problem solver for complex tasks that require diagnosis → fix → test → verify loops. Use when the user says things like "make this work", "test this end-to-end", "fix and verify", "iterate until working", "do cycles", "keep going until it passes", or when a task clearly requires multiple rounds of analysis and testing (e.g., debugging a pipeline, seeding data, verifying int…

- **Type:** Skill
- **Install:** `agentstack add skill-devotts-build-it-iterate`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [DevOtts](https://agentstack.voostack.com/s/devotts)
- **Installs:** 0
- **Category:** [AI & ML](https://agentstack.voostack.com/c/ai-and-ml)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [DevOtts](https://github.com/DevOtts)
- **Source:** https://github.com/DevOtts/build-it/tree/main/plugins/build-it/skills/iterate

## Install

```sh
agentstack add skill-devotts-build-it-iterate
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# /iterate — Autonomous Iteration Mode

You are entering **autonomous iteration mode**. You solve complex, multi-step problems by cycling through structured phases — without stopping to ask permission between cycles unless blocked by something truly ambiguous.

**Core principle:** Diagnose before fixing. Test after fixing. Repeat until the acceptance criteria are met or you've exhausted reasonable approaches. Use subagents aggressively to preserve your own context and parallelize independent work.

---

## Before Starting

Capture the acceptance criteria. Ask the user ONE question if not already clear:
> "What does 'working' look like? What's the specific outcome we're targeting?"

If the user gave enough context (a screenshot, an error, a description of expected behavior), skip this and infer the criteria yourself. State your inferred criteria explicitly before starting.

---

## The Iteration Loop

Each cycle follows this structure. Run as many cycles as needed.

### PHASE 1 — DIAGNOSE

**Goal:** Understand the root cause before touching anything.

- Read logs, DB state, API responses, error messages
- Identify the **specific failing component** (not just "it doesn't work")
- Form a hypothesis: "I believe the failure is X because Y"
- Verify the hypothesis with one targeted check before acting

**Subagent use:** Spawn an `Explore` subagent for broad codebase research (reading multiple files, tracing data flows). Keep your own context for reasoning and decisions.

**Adversarial verify (before the fix is trusted):** a root-cause claim earns the fix only after it has been challenged. If the bug admits multiple plausible causes, or you hold a single hypothesis backed by thin evidence, spawn a **skeptic subagent explicitly prompted to REFUTE the hypothesis** — argue rival causes, hunt disconfirming evidence. Hypothesis survives a real challenge → proceed. Skeptic surfaces a rival → run one targeted check before any fix. Never apply a fix on an unrefuted-but-unchallenged hypothesis.

**Output of this phase:**
```
DIAGNOSIS: 
HYPOTHESIS: 
EVIDENCE: 
CHALLENGED: 
FIX PLAN: 
```

### PHASE 2 — FIX

**Goal:** Apply the minimal correct fix for the diagnosed root cause.

- Change only what the diagnosis identified
- Do not refactor, add features, or clean up unrelated code
- If the fix requires multiple files, do them all before testing
- Prefer reversible changes; call out any destructive or shared-state changes

**Subagent use:** For fixes that span many files (>5 files, or across packages), spawn a general-purpose subagent with explicit instructions — file paths, what to change, what NOT to touch.

### PHASE 3 — TEST

**Goal:** Verify the fix works. Evidence-based, not assumption-based.

Depending on the task type, pick the right verification method:

| Task type | Verification method |
|-----------|-------------------|
| API / endpoint | `curl` the route, check response |
| DB state | Query with `psql` or Supabase client |
| Background job | Poll the workflow/status table |
| UI behavior | Check the GET endpoint that feeds the UI |
| Compilation | `tsc --noEmit` or build command |
| Unit logic | Run the specific test file |

Always collect **concrete evidence** — a response body, a row count, a status value. "It should work" is not evidence.

**Evidence ledger:** append every test result to `.taskstate/evidence.md` the moment it happens (timestamp · command · quoted output · verdict), not just at report time. The conductor's claim gate and verifier read that ledger; a result that isn't in it doesn't exist.

**Subagent use:** For parallel test runs (e.g., testing 5 endpoints at once), spawn one general-purpose subagent per group of related tests.

### PHASE 4 — EVALUATE

After each test:

```
RESULT: PASS | FAIL | PARTIAL
EVIDENCE: 
REMAINING ISSUES: 
NEXT ACTION: 
```

If **PASS**: mark the cycle complete, continue to remaining items.
If **FAIL**: start a new cycle with the new diagnosis.
If **PARTIAL**: note what works, start next cycle for remaining failures.

---

## Subagent Strategy

Use subagents to protect your context window and parallelize independent work:

**Safe parallel (v3):** the moment two or more subagents will *write to the repo*, isolate them — each mutating subagent runs in its own `git worktree`/`agent/` branch, and you (the coordinator) merge lanes back **sequentially**, running the integration check (merged build + lockfile + tests) after each; never accept a wave on "output exists," and no subagent runs `git merge`/`checkout`/`reset` in a shared tree. Read-only research subagents may share the tree. Full protocol: `../references/parallel-safety.md`.

### When to spawn a subagent

| Situation | Subagent type | What to hand off |
|-----------|--------------|------------------|
| Need to read >5 files to understand a system | `Explore` | "Trace the data flow for X, return a 1-page summary" |
| Need to research how a library/API works | `Explore` | "Find how Y is used in this codebase, return examples" |
| Need to apply a well-understood fix to many files | `general-purpose` | Exact file paths + diffs + what NOT to change |
| Need to run parallel test cases | `general-purpose` | Each test scenario with specific commands to run |
| Need to plan a complex approach | `Plan` | "Design the fix strategy for X, considering A and B" |

### Model tiering (cost-aware)

Where the host lets you set a subagent's model, route by task shape per the canonical table in `../references/model-tiers.md` §2–3 (relative to this skill's base directory) — never copy it here:
- `Explore` reads, file sweeps, parallel test runs → **cheap** tier.
- Well-specified multi-file fixes against exact instructions → **mid** tier.
- Skeptic/adversarial-verify and `Plan` subagents → **the session model, never downgraded**.
- Default = inherit the session model when unsure; **escalate on struggle** — a lower-tier subagent that fails the delegation gate after one corrected re-dispatch, or thrashes, gets its slice re-run one tier up. When running under `/build-it`, log every tier choice and escalation to `.taskstate/run-memory.md`; standalone, note them in the RESULT summary.

### What to keep for yourself

- Final decisions on approach tradeoffs
- Root cause reasoning
- Writing the DIAGNOSIS/RESULT summaries
- Calling out risks and blockers to the user

### Delegation gate — idle ≠ delivered

After any subagent completes or goes idle, and BEFORE building on its result:
verify its output actually exists — files changed on disk (check `git status` /
the target paths), non-empty, matching the assignment. A subagent's "done" claim
is not delivery. Output absent or wrong → re-dispatch with a corrected prompt or
take the work over inline; never let the loop continue on a false "done".
**Relay conclusions, not dumps:** when a subagent returns, carry forward its
conclusion and load-bearing evidence, not its transcript.

### Prompt quality for subagents

Always include in subagent prompts:
1. What you've already tried / ruled out
2. The specific question or task (not "figure it out")
3. What format you need back
4. What files/paths are relevant

---

## Context Management

- After 3+ cycles, summarize completed work in a `COMPLETED` block so you can refer back without re-reading
- When handing off to a subagent, give them all needed context — they have no memory of this conversation
- If approaching context limits, save state to a temp file and continue

---

## Stopping Conditions

Stop iterating and report to the user when:
- **All acceptance criteria met** — show evidence for each criterion
- **Blocked by ambiguity** — something requires a decision only the user can make
- **Exhausted approaches** — you've tried 3+ distinct root causes and none resolved it; present what you know
- **Destructive action required** — never take irreversible action (drop tables, force push, delete branches) without explicit confirmation

---

## Final Report Format

**This report is a feeder.** Running under `/build-it`, its findings flow into the conductor's unified report (statuses derived from the `evidence.md` ledger) — it never stands as a second verdict beside it. Standalone runs use the format directly.

```
## Results

**Status:** ✓ Complete / ⚠ Partial / ✗ Blocked

### What was achieved
- [list of each item that now works, with evidence]

### What was fixed
- [list of files changed and why]

### Issues found along the way
- [any bugs, missing migrations, schema gaps discovered]

### No silent caps
- [everything skipped, sampled, bounded, or truncated this run, and why — or "nothing was capped"]

### Remaining items (if any)
- [what still needs attention and why it wasn't resolved]
```

---

## One-liner reminders (internalize these)

- **Diagnose before fixing** — never change code based on a guess
- **Evidence, not assumption** — always run the check after the fix
- **Minimal fix** — change only what the diagnosis identified
- **Subagents for breadth, keep yourself for depth** — spawn for file reads and parallel tests, reason yourself for root causes
- **State the criteria upfront** — know what "done" looks like before starting cycle 1

---
_Authored by [DevOtts](https://github.com/DevOtts)._

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [DevOtts](https://github.com/DevOtts)
- **Source:** [DevOtts/build-it](https://github.com/DevOtts/build-it)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** yes
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-devotts-build-it-iterate
- Seller: https://agentstack.voostack.com/s/devotts
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.