iterate

name	iterate
description	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 integrations, making an API flow work). Also activates when the user wants autonomous QA, test runs, or system-level verification. Splits heavy work across subagents to preserve context and speed up iteration.
metadata	{"author":"DevOtts","author_url":"https://github.com/DevOtts"}

/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.

Output of this phase:

DIAGNOSIS: <one sentence root cause>
HYPOTHESIS: <what I believe is happening>
EVIDENCE: <what confirmed it>
FIX PLAN: <what I'll change>

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.

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: <what you observed>
REMAINING ISSUES: <what still needs fixing>
NEXT ACTION: <next cycle's focus OR "Done">

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:

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"

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

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

When the iteration loop completes, deliver:

## 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]

### 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