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