Iterate

/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: 
HYPOTHESIS: 
EVIDENCE: 
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.

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:

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

---

Authored by 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
• Source: DevOtts/fable-it
• License: MIT

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