iterative-planner（迭代规划器）

Iterative Planner

Core Principle: Context Window = RAM. Filesystem = Disk. Write to disk immediately. The context window will rot. The files won't.

{plan-dir} = plans/plan_YYYY-MM-DD_XXXXXXXX/ (active plan directory under project root). Discovery: plans/.current_plan contains the plan directory name. One active plan at a time. Cross-plan context: plans/FINDINGS.md and plans/DECISIONS.md persist across plans (merged on close). plans/LESSONS.md persists across plans (updated on close, max 200 lines). plans/INDEX.md maps topics to plan directories (survives sliding window trim).

State Machine

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/failed/surprise/leash
    REFLECT --> CLOSE : all criteria met
    REFLECT --> PIVOT : failed / better approach
    REFLECT --> EXPLORE : need more context
    PIVOT --> PLAN : new approach ready
    CLOSE --> [*]

Transitions

Bootstrap shortcuts: bootstrap.mjs close allows closing from any state (EXPLORE→CLOSE, PLAN→CLOSE, EXECUTE→CLOSE, PIVOT→CLOSE). These are administrative exits — the protocol CLOSE steps (summary.md, decision audit, LESSONS.md update) should be completed by the agent before running close.

Every transition → log in state.md. PIVOT transitions → also log in decisions.md (what failed, what learned, why new direction). At CLOSE → audit decision anchors (references/decision-anchoring.md). Merge per-plan findings/decisions to plans/FINDINGS.md and plans/DECISIONS.md. Update plans/LESSONS.md with significant lessons (rewrite to ≤200 lines). Compress consolidated files if >500 lines (see "Consolidated File Management").

Protocol Tiers

Checks marked *(EXTENDED)* in the per-state rules may be skipped for iteration 1 single-pass plans. All other checks are CORE — always enforced. EXTENDED checks add value for multi-iteration plans where anchoring bias, ghost constraints, and prediction drift are real risks.

Mandatory Re-reads (CRITICAL)

These files are active working memory. Re-read during the conversation, not just at start.

>50 messages: re-read state.md + plan.md before every response. Files are truth, not memory.

Bootstrapping

node <skill-path>/scripts/bootstrap.mjs "goal"              # Create new plan (backward-compatible)
node <skill-path>/scripts/bootstrap.mjs new "goal"           # Create new plan
node <skill-path>/scripts/bootstrap.mjs new --force "goal"   # Close active plan, create new one
node <skill-path>/scripts/bootstrap.mjs resume               # Re-entry summary for new sessions
node <skill-path>/scripts/bootstrap.mjs status               # One-line state summary
node <skill-path>/scripts/bootstrap.mjs close                # Close plan (preserves directory)
node <skill-path>/scripts/bootstrap.mjs list                 # Show all plan directories
node <skill-path>/scripts/validate-plan.mjs                  # Validate active plan compliance

new refuses if active plan exists — use resume, close, or --force. new ensures .gitignore includes plans/ — prevents plan files from being committed during EXECUTE step commits. close merges per-plan findings/decisions to consolidated files, updates state.md, appends to plans/INDEX.md, snapshots plans/LESSONS.md to the plan directory, and removes the .current_plan pointer. The protocol CLOSE state (writing summary.md, auditing decision anchors, updating plans/LESSONS.md) should be completed by the agent before running close. After bootstrap → read every file in {plan-dir} (state.md, plan.md, decisions.md, findings.md, progress.md, verification.md) before doing anything else. Then begin EXPLORE. User-provided context → write to findings.md first.

Filesystem Structure

plans/
├── .current_plan                  # → active plan directory name
├── FINDINGS.md                    # Consolidated findings across all plans (merged on close)
├── DECISIONS.md                   # Consolidated decisions across all plans (merged on close)
├── LESSONS.md                     # Cross-plan lessons learned (≤200 lines, rewritten on close)
├── INDEX.md                       # Topic→directory mapping (updated on close, survives trim)
└── plan_2026-02-14_a3f1b2c9/      # {plan-dir}
    ├── state.md                   # Current state + transition log
    ├── plan.md                    # Living plan (rewritten each iteration)
    ├── decisions.md               # Append-only decision/pivot log
    ├── findings.md                # Summary + index of findings
    ├── findings/                  # Detailed finding files (subagents write here)
    ├── progress.md                # Done vs remaining
    ├── verification.md            # Verification results per REFLECT cycle
    ├── checkpoints/               # Snapshots before risky changes
    ├── lessons_snapshot.md        # LESSONS.md snapshot at close (auto-created)
    └── summary.md                 # Written at CLOSE

Templates: references/file-formats.md

File Lifecycle Matrix

R = read only | W = update (implicit read + write) | R+W = distinct read and write operations | — = do not touch (wrong state if you are).

Read-before-write rule: Always read a plan file before writing/overwriting it — even on the first update after bootstrap. Claude Code's Write tool will reject writes to files you haven't read in the current session. This applies to every W and R+W cell below.

Consolidated File Management

plans/FINDINGS.md and plans/DECISIONS.md grow across plans. Two mechanisms prevent context window bloat:

Sliding window: Bootstrap automatically trims consolidated files to the 8 most recent plan sections on each close. Old plan sections are removed from the consolidated file but remain in their per-plan directories (plans/plan_*/findings.md, plans/plan_*/decisions.md). This keeps files naturally bounded at ~300-450 lines.

Read limit: Always read consolidated files with limit: 600. The compressed summary + most recent plan sections fit within this.

Compression (rarely needed — sliding window keeps files bounded): Threshold: >500 lines → compressed summary needed. Bootstrap prints ACTION NEEDED after merge.

Compression protocol (during CLOSE, after merge):

1. Check line count. If ≤500 → no action needed.
2. If >500 and NO <!-- COMPRESSED-SUMMARY --> marker exists → create new summary.
3. If >500 and marker already exists → REPLACE content between markers. Never summarize the old summary — read only the raw plan sections below the markers to write the new summary.

Format — insert between H1 header and first ## plan_ section:

<!-- COMPRESSED-SUMMARY -->
## Summary (compressed)
*Auto-compressed from N lines. Read full content below line 600 if needed.*

### Key Findings
- (≤50 lines of consolidated findings across all plans)

### Key Decisions
- (≤50 lines of consolidated decisions across all plans)
<!-- /COMPRESSED-SUMMARY -->

Rules:

• Max 100 lines between markers (total, including section headers).
• Focus on: outcomes, active constraints, things NOT to do (failed approaches), anchored decisions.
• Drop: iteration details, timestamps, verbose reasoning — those survive in full content below.
• Failsafe: when writing the summary, SKIP everything between <!-- COMPRESSED-SUMMARY --> and <!-- /COMPRESSED-SUMMARY --> markers. Only summarize the actual plan sections (## plan_*). This prevents summaries of summaries.

Lessons Learned (plans/LESSONS.md)

Institutional memory across plans. Unlike FINDINGS.md and DECISIONS.md which grow via append+merge, LESSONS.md is rewritten to stay ≤200 lines.

When to update: At CLOSE, before running bootstrap.mjs close. Read the current file, integrate significant lessons from the plan, and rewrite the entire file — consolidating, deduplicating, and pruning stale entries.

When to read: Before PLAN, before PIVOT, and at start of EXPLORE. This is the first thing to check for institutional memory — what patterns work, what doesn't, what to avoid.

Rules:

• Hard cap: 200 lines. If an update would exceed 200 lines, consolidate aggressively — merge related lessons, drop low-value entries, tighten wording.
• Rewrite, don't append. Each update produces a complete, self-contained file. No "added on date X" markers.
• Focus on: recurring patterns, failed approaches and why, successful strategies, codebase-specific gotchas, constraints that surprised you.
• Drop: one-off findings (those belong in FINDINGS.md), detailed decision reasoning (that's in DECISIONS.md), anything plan-specific that won't help future plans.
• Created automatically by bootstrap on first new.

Per-State Rules

EXPLORE

• Read state.md, plans/FINDINGS.md and plans/DECISIONS.md (limit: 600 lines), plans/LESSONS.md, and plans/INDEX.md at start of EXPLORE for cross-plan context. INDEX.md helps locate old findings that have been trimmed from consolidated files.
• Read code, grep, glob, search. One focused question at a time.
• Flush to findings.md + findings/ after every 2 reads. Read the file first before each write.
• Include file paths + code path traces (e.g. auth.rb:23 → SessionStore#find → redis_store.rb:get).
• DO NOT skip EXPLORE even if you think you know the answer.
• Minimum depth: ≥3 indexed findings in findings.md before transitioning to PLAN. Findings must cover: (1) problem scope, (2) affected files, (3) existing patterns or constraints. Fewer than 3 → keep exploring.
• Exploration Confidence — before transitioning to PLAN, self-assess: problem scope [shallow/adequate/deep], solution space [narrow/open/constrained], risk visibility [blind/partial/clear]. All must be at least "adequate." Any "shallow" or "blind" → keep exploring. Record in the transition log entry in state.md. See references/planning-rigor.md.
• Constraint classification — when documenting constraints in findings.md, classify each as:

- Hard constraint: non-negotiable (physics, budget, existing systems, regulations, deadlines). - Soft constraint: preferences, conventions, team familiarity — negotiable if trade-off is explicit. - Ghost constraint: past constraints baked into current approach that no longer apply. Finding and removing ghost constraints unlocks options nobody thought were available. Separate constraints from preferences — be honest about which is which. Can't distinguish them → keep exploring.

• Use Task subagents to parallelize research. All subagent output → {plan-dir}/findings/ files. Never rely on context-only results. Main agent updates findings.md index after subagents write — subagents don't touch the index. Naming: findings/{topic-slug}.md (kebab-case, descriptive — e.g. auth-system.md, test-coverage.md).
• Use "think hard" / "ultrathink" for complex analysis.
• REFLECT → EXPLORE loops: append to existing findings, don't overwrite. Mark corrections with [CORRECTED iter-N].

PLAN

• Gate check: read state.md, plan.md, findings.md, findings/*, decisions.md, progress.md, verification.md, plans/FINDINGS.md (limit: 600), plans/DECISIONS.md (limit: 600), plans/LESSONS.md before writing anything. If not read → read now. No exceptions. If findings.md has <3 indexed findings → go back to EXPLORE.
• Problem Statement first — before designing steps, write in plan.md: (1) what behavior is expected, (2) invariants — what must always be true, (3) edge cases at boundaries. Can't state the problem clearly → go back to EXPLORE.
• Write plan.md: problem statement, steps (with risk/dependency annotations), assumptions, failure modes, pre-mortem & falsification signals, success criteria, verification strategy, complexity budget.
• Decomposition — when breaking the goal into steps:

1. Understand the whole problem before splitting into parts. Resist diving into details. 2. Identify natural boundaries — where do concerns separate? 3. Minimize dependencies between steps. If two steps must always change together, they're one step. 4. Start with the hardest or riskiest part (most unknowns). Easier parts rarely invalidate the plan. 5. When unsure whether to split or merge: split when concerns change for different reasons; merge when split pieces always change together or the split creates more coordination overhead than it removes.

• Verification Strategy — for each success criterion, define: what test/check to run, what command to execute, what result means "pass". Write to plan.md Verification Strategy section. Plans with no testable criteria → write "N/A — manual review only" (proves you checked). See references/file-formats.md for template.
• Assumptions — bullet list in plan.md: what you assume, which finding grounds it, which steps depend on it. On surprise discovery during EXECUTE → check this list first. See references/planning-rigor.md.
• Failure Mode Analysis — for each external dependency or integration point in the plan, answer: what if slow? returns garbage? is down? What's the blast radius? Write to plan.md Failure Modes section. No dependencies → write "None identified" (proves you checked).
• Pre-Mortem & Falsification Signals — assume the plan failed. 2-3 scenarios with concrete STOP IF triggers. If a trigger fires during EXECUTE → stop and REFLECT. Covers approach validity (distinct from Failure Modes which cover dependencies, and Autonomy Leash which covers step failure). See references/planning-rigor.md.
• Write decisions.md: log chosen approach + why (mandatory even for first plan). Trade-off rule — phrase every decision as "X at the cost of Y". Never recommend without stating what it costs.
• Read then write verification.md with initial template (criteria table populated from success criteria, methods from verification strategy, results pending).
• Read then write state.md + progress.md.
• List every file to modify/create. Can't list them → go back to EXPLORE.
• Only recommended approach in plan. Alternatives → decisions.md.
• Wait for explicit user approval.

EXECUTE

• Pre-Step Checklist in state.md: reset all boxes [], then check each [x] as completed before starting the step. This is the file-based enforcement of Mandatory Re-reads.
• Iteration 1, first EXECUTE → create checkpoints/cp-000-iter1.md (nuclear fallback). "Git State" = commit hash BEFORE changes (the restore point).
• One step at a time. Post-Step Gate after each (see below).
• Checkpoint before risky changes (3+ files, shared modules, destructive ops). Name: cp-NNN-iterN.md (e.g. cp-001-iter2.md). Increment NNN globally across iterations.
• Commit after each successful step: [iter-N/step-M] description.
• If something breaks → STOP. 2 fix attempts max (Autonomy Leash). Each must follow Revert-First.
• Irreversible operations (DB migrations, external API calls, service config, non-tracked file deletion): mark step [IRREVERSIBLE] in plan.md during PLAN. Full procedure: references/code-hygiene.md.
• Surprise discovery (behavior contradicts findings, unknown dependency, wrong assumption) → check plan.md Assumptions to identify which steps are invalidated. Note in state.md, finish or revert current step, transition to REFLECT. Do NOT silently update findings during EXECUTE.
• Falsification signal fires (from Pre-Mortem & Falsification Signals in plan.md) → same as surprise discovery. Log which signal fired in decisions.md.
• Add # DECISION D-NNN comments where needed (references/decision-anchoring.md).

Post-Step Gate (successful steps only — all 3 before moving on)

1. plan.md — mark step [x], advance marker, update complexity budget
2. progress.md — move item Remaining → Completed, set next In Progress
3. state.md — update step number, append to change manifest

On failed step: skip gate. Follow Autonomy Leash (revert-first, 2 attempts max).

REFLECT

Three phases: Gate-In (gather context), Evaluate (verify + analyze), Gate-Out (decide + present).

Phase 1: Gate-In (mandatory reads before any evaluation)

1. Read plan.md — success criteria, verification strategy, assumptions, pre-mortem signals.
2. Read progress.md — what was completed, what remains, what failed.
3. Read verification.md — previous verification results (if iteration 2+).
4. Read findings.md + relevant findings/* — check if EXECUTE discoveries contradict earlier findings. Note contradictions in decisions.md.
5. Read checkpoints/* — know rollback options before deciding next transition. Note available restore points in decisions.md if transitioning to PIVOT.
6. Read decisions.md — check 3-strike patterns, review previous REFLECT cycles (iteration 2+).

All six reads are CORE. Do not evaluate until all are complete.

Phase 2: Evaluate

1. Cross-validate plan vs progress — every [x] in plan.md must be "Completed" in progress.md. Fix drift before proceeding.
2. Diff review — review actual code changes (git diff or change manifest in state.md). Check for: debug artifacts, commented-out code, TODO/FIXME/HACK leftovers, unintended modifications to files not in the plan. This checks code quality; verification (next) checks correctness.
3. Run verification — execute each check from the Verification Strategy. Read verification.md, then record results: criterion, method, command/action, result (PASS/FAIL), evidence (output summary or log reference). See references/file-formats.md for template.
4. Regression check — re-run any tests that passed before this iteration. If a previously-passing test now fails, record as FAIL in Additional Checks with "regression" noted in Details. Regressions block CLOSE.
5. Scope drift check — compare files actually changed (change manifest in state.md) against Files To Modify in plan.md. Unplanned file changes must be justified in decisions.md or reverted. Criteria can pass even when implementation has drifted.
6. Criteria adequacy — before accepting PASS results, ask: do these criteria test what matters, or what was easy to test? Are there behaviors the criteria don't cover? Record gaps in verification.md Not Verified section.
7. Not-verified list — in verification.md, write what you didn't test and why (no coverage, out of scope, untestable). Absence of evidence is not evidence of absence.
8. Root cause analysis (when REFLECT follows failure) — in decisions.md, answer: (1) What was the immediate cause? (2) What allowed it? (trace back one level) (3) What would have caught it earlier? (prevention). Skip if all criteria PASS on first attempt. See references/planning-rigor.md.
9. Run 6 Simplification Checks (references/complexity-control.md). Compare against written criteria, not memory.
10. Run validate-plan.mjs — protocol compliance check. Address ERRORs before CLOSE. WARNs are advisory.
11. Prediction accuracy *(EXTENDED — skip for iteration 1)* — compare plan.md predictions against actual results. Record in verification.md Prediction Accuracy table. See references/planning-rigor.md.
12. Convergence score *(EXTENDED — iteration 2+)* — compute pass rate trend, scope stability, issue decay. Record in verification.md Convergence Metrics table. Stalling/diverging scores strengthen case for PIVOT or decomposition — don't wait for iteration 5. See references/convergence-metrics.md.
13. Devil's advocate *(EXTENDED — skip for iteration 1)* — before routing to CLOSE: name one reason this might still be wrong despite passing verification. If you can't think of one, be more suspicious, not less. Record in decisions.md.
14. Adversarial review *(EXTENDED — iteration 2+ only)* — spawn a Task subagent with verification.md, plan.md (criteria), and decisions.md. Its job: are criteria adequate? what wasn't tested? does evidence support CLOSE? Main agent must address each concern in decisions.md before routing to CLOSE.

Phase 3: Gate-Out (write + present)

1. Write verification.md — complete Verdict section.
2. Write decisions.md — what happened, what was learned, root cause (if failure). Include Simplification Checks output.
3. Write progress.md — update status of all items.
4. Write state.md — log evaluation summary, update transition.

Present to user before routing:

1. What was completed (from progress.md)
2. What remains (if anything)
3. Verification results summary (PASS/FAIL counts from verification.md)
4. Issues found: regressions, scope drift, unverified areas, simplification blockers
5. Recommend: close, pivot, or explore — wait for user confirmation

PIVOT

• Read decisions.md, findings.md, relevant findings/*, plans/LESSONS.md.
• Read checkpoints/* — decide keep vs revert. Default: if unsure, revert to latest checkpoint. See references/code-hygiene.md for full decision framework.
• Ghost constraint scan *(EXTENDED — skip for iteration 1)* — before designing a new approach, ask: (1) Is the constraint that led to the failed approach still valid? (2) Are we inheriting environmental constraints that are actually preferences? (3) Did an early finding become stale? Log ghost constraints found in decisions.md. See references/planning-rigor.md.
• If earlier findings proved wrong or incomplete → update findings.md + findings/* with corrections. Mark corrections: [CORRECTED iter-N] + what changed and why. Append, don't delete original text.
• Momentum check *(EXTENDED — 2nd PIVOT onward)* — log pivot direction, check for oscillation. Momentum < 0.3 → recommend decomposition. See references/convergence-metrics.md.
• Write decisions.md: log pivot + mandatory Complexity Assessment (+ pivot direction log if EXTENDED).
• Write state.md + progress.md (mark failed items, note pivot).
• Present options to user → get approval → transition to PLAN.

Complexity Control (CRITICAL)

Default response to failure = simplify, not add. See references/complexity-control.md.

Revert-First — when something breaks: (1) STOP (2) revert? (3) delete? (4) one-liner? (5) none → REFLECT. 10-Line Rule — fix needs >10 new lines → it's not a fix → REFLECT. 3-Strike Rule — same area breaks 3× → PIVOT with fundamentally different approach. Revert to checkpoint covering the struck area. Complexity Budget — tracked in plan.md: files added 0/3, abstractions 0/2, lines net-zero target. Forbidden: wrapper cascades, config toggles, copy-paste, exception swallowing, type escapes, adapters, "temporary" workarounds. Nuclear Option — iteration 5 + bloat >2× scope → recommend full revert to cp-000 (or later checkpoint if user agrees). Otherwise proceed with caution. See references/complexity-control.md.

Autonomy Leash (CRITICAL)

When a step fails during EXECUTE:

1. 2 fix attempts max — each must follow Revert-First + 10-Line Rule.
2. Both fail → STOP COMPLETELY. No 3rd fix. No silent alternative. No skipping ahead.
3. Revert uncommitted changes to last clean commit. Codebase must be known-good before presenting.
4. Present: what step should do, what happened, 2 attempts, root cause guess, available checkpoints for rollback.
5. Transition → REFLECT. Log leash hit in state.md. Wait for user.

Track attempts in state.md. Resets on: user direction, new step, or PIVOT. No exceptions. Unguided fix chains derail projects.

Code Hygiene (CRITICAL)

Failed code must not survive. Track changes in change manifest in state.md. Failed step → revert all uncommitted. PIVOT → explicitly decide keep vs revert. Codebase must be known-good before any PLAN. See references/code-hygiene.md.

Decision Anchoring (CRITICAL)

Code from failed iterations carries invisible context. Anchor # DECISION D-NNN at point of impact — state what NOT to do and why. Audit at CLOSE. See references/decision-anchoring.md.

Iteration Limits

Increment on PLAN → EXECUTE. Iteration 0 = EXPLORE-only (pre-plan). First real = iteration 1.

• Iteration 5: mandatory decomposition analysis in decisions.md — identify 2-3 independent sub-goals that could each be a separate plan, with dependencies between them. See references/planning-rigor.md.
• Iteration 6+: hard STOP. Present decomposition analysis to user. Break into smaller tasks.

Recovery from Context Loss

1. If plans/.current_plan is missing or corrupted: run bootstrap.mjs list to find plan directories, then recreate the pointer: echo "plan_YYYY-MM-DD_XXXXXXXX" > plans/.current_plan (substitute actual directory name).
2. plans/.current_plan → plan dir name
3. state.md → where you are
4. plan.md → current plan
5. decisions.md → what was tried / failed
6. progress.md → done vs remaining
7. findings.md + findings/* → discovered context
8. checkpoints/* → available rollback points and their git hashes
9. plans/FINDINGS.md + plans/DECISIONS.md → cross-plan context from previous plans
10. plans/LESSONS.md → institutional memory (read before planning)
11. plans/INDEX.md → topic-to-directory mapping (find old findings by topic when sliding window has trimmed them)
12. Resume from current state. Never start over.

Git Integration

• EXPLORE/PLAN/REFLECT/PIVOT: no commits.
• EXECUTE: commit per successful step [iter-N/step-M] desc. Failed step → revert uncommitted.
• PIVOT: keep successful commits if valid under new plan, or git checkout <checkpoint-commit> --. to revert. No partial state. Log choice in decisions.md.
• CLOSE: final commit + tag.

User Interaction

When NOT to Use

Simple single-file changes, obvious solutions, known-root-cause bugs, or "just do it".

References

• references/file-formats.md — templates for all {plan-dir} files
• references/complexity-control.md — anti-complexity protocol, forbidden patterns
• references/code-hygiene.md — change manifest, revert procedures
• references/decision-anchoring.md — when/how to anchor decisions in code
• references/planning-rigor.md — assumption tracking, pre-mortem, falsification signals, exploration confidence, prediction accuracy
• references/convergence-metrics.md — convergence score, momentum tracker, iteration health signals