Iterative Planner

A Claude Code skill that turns ad-hoc agent runs into structured, recoverable, evidence-driven work.

Without structure, Claude plans once, hits a wall, and layers fixes on fixes until it loses track of what it already tried. Iterative Planner forces a state machine — Explore, Plan, Execute, Reflect, Pivot, Close — and writes every decision, finding, and pivot to disk. The filesystem is persistent working memory. The context window can rot; the plan directory cannot.

Works for refactoring, migrations, debugging, system design, deep research — anything where "just do it" leads to a mess.

---

Table of Contents

• When to Use This
• How It Works
• A Worked Example
• Why This Works
• Get Started in 60 Seconds
• The Plan Directory
• Bootstrapping
• Sub-Agent Architecture
• Presentation Contracts
• Validator
• Git Integration
• FAQ
• Contributing
• Project Structure
• Sponsored by
• License

---

When to Use This

Use it	Skip it
Multi-step tasks touching 3+ files or 2+ systems	Single-file, single-step changes
Migrations, refactors, architectural changes	Well-known, straightforward solutions
Tasks that have already failed once	Quick fixes where you already know the answer
Complex research or analysis with many moving parts	One-shot questions
System design and technical decision-making
Debugging where the root cause is unclear
Anything where you'd benefit from "what did I already try?"

Trigger phrases: "plan this", "figure out", "help me think through", "I've been struggling with", "debug this complex issue".

---

How It Works

Six states. Every transition is logged. Every decision is recorded. The filesystem is the source of truth.

stateDiagram-v2
    [*] --> EXPLORE
    EXPLORE --> PLAN : enough context
    PLAN --> EXPLORE : need more context
    PLAN --> PLAN : user rejects, revise
    PLAN --> EXECUTE : user approves
    EXECUTE --> REFLECT : phase ends, fails, or autonomy leash hits
    REFLECT --> CLOSE : criteria PASS, user confirms
    REFLECT --> PIVOT : failed or better approach
    REFLECT --> EXPLORE : need more context
    PIVOT --> PLAN : new approach ready
    CLOSE --> [*]

If your viewer does not render mermaid, use the table below.

State	What happens	Guardrails
EXPLORE	Read, search, ask. Pull cross-plan findings, decisions, lessons, and the system atlas.	Read-only on the project. All notes go to the plan directory. Minimum 3 indexed findings before PLAN.
PLAN	Design the approach. Identify every artifact to create or modify. Write success criteria, verification strategy, assumptions, failure modes, and a pre-mortem.	No code changes. User must approve before execution.
EXECUTE	Implement one step at a time. Commit after each success. Append a per-edit changelog line for every file edited.	2 fix attempts max. Revert-first on failure. Surprises trigger REFLECT.
REFLECT	Three phases: Gate-In (read everything), Evaluate (verify, diff review, regression check, scope drift, root cause, run validator), Gate-Out (write results, present to user).	Evidence-based only. Regressions and simplification blockers prevent CLOSE. Contradicted findings trigger EXPLORE.
PIVOT	Diagnose the failure, hunt for ghost constraints, propose a new direction.	Must explain what failed and why. User approves new direction.
CLOSE	Write summary. Audit decision anchors. Merge knowledge into consolidated files. Rewrite LESSONS.md and SYSTEM.md.	Verify clean output. No leftover artifacts.

Iteration limits

Iterations increment on each PLAN → EXECUTE transition.

• Iteration 5: mandatory decomposition analysis — identify 2-3 independent sub-goals that could each be a separate plan.
• Iteration 6+: hard stop. Decomposition is presented and the task must be broken up.

This prevents the runaway "one more iteration" pattern that destroys plans.

---

A Worked Example

Here is a complete cycle, condensed.

You: "I want to migrate our auth from session cookies to stateless JWTs. Plan this."

Claude (EXPLORE) runs bootstrap.mjs new "Migrate auth from session cookies to JWT", creates plans/plan_2026-05-07_a3f1b2c9/, then:

• Reads plans/FINDINGS.md, plans/DECISIONS.md, plans/LESSONS.md, plans/SYSTEM.md for cross-plan context.
• Spawns 2-3 ip-explorer sub-agents in parallel: one maps the auth surface, one inventories existing JWT usage, one examines the test suite.
• Writes results to findings/auth-system.md, findings/jwt-current.md, findings/test-coverage.md.
• Classifies constraints: HARD (existing OAuth providers must keep working), SOFT (team prefers jose over jsonwebtoken), GHOST (a 5-year-old comment about Redis cluster topology that no longer applies).

Claude (PLAN) writes plan.md with:

• Problem Statement — expected behavior, invariants, edge cases.
• Steps — each annotated [RISK: low/medium/high] and [deps: N,M]. Riskiest first.
• Success Criteria + Verification Strategy — every criterion has a test command and a pass condition.
• Assumptions — each traced to a finding.
• Failure Modes — what if the JWT library is slow, returns garbage, or is down.
• Pre-Mortem & Falsification Signals — "STOP IF p99 latency increases more than 20ms."

Claude presents the plan as a PC-PLAN block (verbatim — not a paraphrase). You approve or push back. If you push back, Claude revises and re-presents the same contract.

Claude (EXECUTE) implements step 1. After each file edit, an entry is appended to changelog.md recording timestamp, step, commit, file, op, blast-radius score, decision-ref, and reason. After each successful step:

• plan.md step marked [x].
• progress.md updated.
• state.md change manifest extended.
• Commit: [iter-1/step-1] add JWT verifier.

If a step fails: revert uncommitted, two fix attempts max, each constrained by the Revert-First and 10-Line rules. Both fail → STOP, present, ask you.

Claude (REFLECT) runs the verifier. The PASS/FAIL table from verification.md is rendered verbatim in the PC-REFLECT block. If it is iteration 2+, an ip-reviewer sub-agent runs an adversarial review and its concerns are folded in verbatim. Claude recommends close, pivot, or explore. You decide.

Claude (CLOSE) spawns ip-archivist to write summary.md, audit # DECISION plan_2026-05-07_a3f1b2c9/D-NNN anchors in source, rewrite plans/LESSONS.md (≤200 lines), and rewrite the plans/SYSTEM.md atlas (≤300 lines). Then bootstrap.mjs close merges per-plan findings and decisions into the consolidated cross-plan files (sliding window of the 4 most recent plans).

The next plan starts with all of this on disk, available to read.

---

Why This Works

Five properties separate this from "ask Claude to make a plan."

Persistent memory

Everything important lives on disk, not the context window. State, decisions, findings, progress, and verification results are recoverable across conversation restarts. Mandatory re-reads keep the agent grounded: state.md is re-read every 10 tool calls; after 50 messages, state.md and plan.md are re-read before every response. The context window can rot mid-task; the plan directory cannot.

Cross-plan intelligence

When a plan closes, its findings and decisions merge into consolidated files at the plans/ root, and the next plan reads them during EXPLORE. Migrations build on earlier debugging sessions; design plans inherit constraints discovered during prior research; failed approaches stay visible so future plans don't repeat dead ends. A sliding window keeps the consolidated files to the 4 most recent plans (older sections stay intact in their own directories, indexed by plans/INDEX.md).

Alongside the goal-driven findings sits the system atlas (plans/SYSTEM.md): a curated, domain-neutral map of what the system being planned against actually is — Identity, Components, Boundaries, Invariants, Flows, Known Patterns. Capped at 300 lines, rewritten at CLOSE, read at the start of every EXPLORE and PLAN. It is the structural prior the agent carries into every new plan.

Self-correcting research

Every discovery is written to findings.md with file paths, code-path traces, and evidence. The agent cannot transition to PLAN until it has at least 3 indexed findings covering problem scope, affected areas, and existing patterns. When execution proves a finding wrong, it gets a [CORRECTED iter-N] marker — the original stays for traceability.

The autonomy leash

When a step fails during EXECUTE, the agent gets 2 fix attempts, each constrained to reverting, deleting, or a minimal change. If neither works, it stops, reverts uncommitted changes, presents what happened, and asks you. No silent third attempts. No "one more try." This is the single most important rule for keeping unattended agent work safe.

Revert-first complexity control

The default response to failure is to simplify, never to add: can I fix by reverting? deleting? a one-line change? If none of those — stop and enter REFLECT. Hard limits back this up:

Rule	What it does
10-Line Rule	If a "fix" needs more than 10 new lines, it's not a fix. It needs a plan.
3-Strike Rule	Same area breaks 3 times? The approach is wrong. Mandatory PIVOT, with revert to a covering checkpoint.
Complexity Budget	Max 3 new files, max 2 new abstractions, target net-zero or negative line count. Tracked in plan.md.
Nuclear Option	At iteration 5, scope doubled? Recommend full revert to the iteration-1 checkpoint. The decision log preserves all learnings.
6 Simplification Checks	Structured REFLECT diagnostic: delete instead? symptom or root cause? essential or accidental complexity? fighting the framework? worth reverting everything?

Reasoning frameworks built into each state

Each state embeds domain-agnostic thinking tools so the rigor is structural, not improvised:

Framework	State	What it does
Constraint classification	EXPLORE	Tag every constraint hard, soft, or ghost (no longer applies). Ghost constraints reveal previously blocked options.
Exploration confidence	EXPLORE	Self-assess scope, solution space, risk visibility. "Shallow" on any dimension means keep exploring.
Problem decomposition	PLAN	Understand the whole, find natural boundaries, minimize dependencies, start with the riskiest part.
Assumption tracking	PLAN	Every assumption traced to a finding and linked to dependent steps. When one breaks, you know what's invalidated.
Pre-mortem & falsification	PLAN	Assume the plan failed. Why? Extract concrete STOP IF triggers. Counters confirmation bias.
Prediction accuracy	REFLECT	Compare predicted vs actual step/file/line counts. Calibrates future estimates via LESSONS.md.
Root cause analysis	REFLECT	On failure: immediate cause, contributing factor, failed defense, prevention. Stop rule against premature closure.
Essential vs accidental complexity	REFLECT	"Inherent in the problem, or did we create it?" Essential = partition. Accidental = remove.
Ghost-constraint hunting	PIVOT	Before pivoting, check whether the constraint behind the failed approach is still valid.

Audit trail and clean output

Three mechanisms keep the workspace honest, all visible on disk:

• Decision anchoring — when code survives a failed alternative, the agent leaves a plan-qualified # DECISION plan_YYYY-MM-DD_XXXXXXXX/D-NNN comment at the point of impact, stating what not to do and why. The plan-id prefix stays resolvable even after the consolidated plans/DECISIONS.md sliding-window trim. The validator audits every anchor at CLOSE. (Details: src/references/decision-anchoring.md.)
• Per-edit changelog + blast-radius scoring — every file edit appends one line to {plan-dir}/changelog.md (timestamp, iter/step, commit, path, op, blast-radius tier, decision-ref, reason). A deterministic scorer tiers each edit LOW/MED/HIGH and surfaces "tiny edit, big radius" outliers that plan-level failure modes miss. Always advisory, never blocks CLOSE. (Details: src/references/blast-radius.md.)
• Clean output hygiene — every change is tracked in a manifest, failed steps revert immediately, and forbidden leftovers (TODOs, debug prints, commented-out code, orphan helpers) are flagged at REFLECT. The workspace is always known-good before new work begins.

---

Get Started in 60 Seconds

Requires: Node.js 18+ (for the bootstrap and validator scripts).

Option 1 — Zip package (recommended)

Download the latest zip from Releases and unzip into your local skills directory:

unzip iterative-planner-v*.zip -d ~/.claude/skills/

Option 2 — Single-file