iterative-planner

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

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

核心原则：上下文窗口 = 内存（RAM）。文件系统 = 磁盘（Disk）。立即写入磁盘。上下文窗口会失效，但文件不会。

{plan-dir}
=

plans/plan_YYYY-MM-DD_XXXXXXXX/

（项目根目录下的活跃计划目录）。 发现机制：

plans/.current_plan

文件存储计划目录名称。同一时间仅存在一个活跃计划。 跨计划上下文：

plans/FINDINGS.md

和

plans/DECISIONS.md

文件会在所有计划间持久化（关闭计划时合并）。

State Machine

状态机

mermaid

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 --> RE_PLAN : failed / better approach
    REFLECT --> EXPLORE : need more context
    RE_PLAN --> PLAN : new approach ready
    CLOSE --> [*]

State	Purpose	Allowed Actions
EXPLORE	Gather context	Read-only on project. Write only to `{plan-dir}` .
PLAN	Design approach	Write plan.md. NO code changes.
EXECUTE	Implement step-by-step	Edit files, run commands, write code.
REFLECT	Evaluate results	Read outputs, run tests. Update decisions.md.
RE-PLAN	Revise direction	Log pivot in decisions.md. Do NOT write plan.md yet.
CLOSE	Finalize	Write summary.md. Audit decision anchors. Merge findings/decisions to consolidated files.

mermaid

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 --> RE_PLAN : failed / better approach
    REFLECT --> EXPLORE : need more context
    RE_PLAN --> PLAN : new approach ready
    CLOSE --> [*]

状态	目标	允许的操作
EXPLORE（探索）	收集上下文	仅可读项目文件，仅可写入 `{plan-dir}`
PLAN（规划）	设计实现方案	写入plan.md，禁止修改代码
EXECUTE（执行）	分步实现	编辑文件、运行命令、编写代码
REFLECT（反思）	评估结果	读取输出、运行测试、更新decisions.md
RE-PLAN（重新规划）	调整方向	在decisions.md中记录转向，暂不写入plan.md
CLOSE（关闭）	最终收尾	写入summary.md，审核决策锚点，将发现/决策合并到统一文件中

Transitions

状态转换

From → To	Trigger
EXPLORE → PLAN	Sufficient context. ≥3 indexed findings in `findings.md` .
PLAN → EXPLORE	Can't state problem, can't list files, or insufficient findings.
PLAN → PLAN	User rejects plan. Revise and re-present.
PLAN → EXECUTE	User explicitly approves.
EXECUTE → REFLECT	Execution phase ends (all steps done, failure, surprise, or leash hit).
REFLECT → CLOSE	All criteria verified PASS in `verification.md` .
REFLECT → RE-PLAN	Failure or better approach found.
REFLECT → EXPLORE	Need more context before re-planning.
RE-PLAN → PLAN	New approach formulated. Decision logged.

Every transition → log in

state.md

. RE-PLAN 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

起始→目标	触发条件
探索→规划	上下文足够， `findings.md` 中至少有3条索引化的发现
规划→探索	无法明确问题、无法列出相关文件，或发现内容不足
规划→规划	用户拒绝当前规划，需要修订后重新提交
规划→执行	用户明确批准规划
执行→反思	执行阶段结束（所有步骤完成、执行失败、出现意外或触发自主限制）
反思→关闭	`verification.md` 中所有验证标准均通过
反思→重新规划	执行失败或发现更优方案
反思→探索	重新规划前需要更多上下文
重新规划→规划	新方案已确定，决策已记录

每次状态转换→记录到

state.md

中。重新规划的转换→同时记录到

decisions.md

（包括失败原因、经验总结、转向新方案的理由）。关闭阶段→审核决策锚点（

references/decision-anchoring.md

）。将当前计划的发现/决策合并到

plans/FINDINGS.md

和

plans/DECISIONS.md

中。

Mandatory Re-reads (CRITICAL)

强制重读规则（至关重要）

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

When	Read	Why
Before any EXECUTE step	`state.md` , `plan.md` , `progress.md`	Confirm step, manifest, fix attempts, progress sync
Before writing a fix	`decisions.md`	Don't repeat failed approaches. Check 3-strike.
Before modifying `DECISION` -commented code	Referenced `decisions.md` entry	Understand why before changing
Before PLAN or RE-PLAN	`decisions.md` , `findings.md` , `findings/*`	Ground plan in known facts
Before any REFLECT	`plan.md` (criteria), `progress.md` , `verification.md`	Compare against written criteria, not vibes
Every 10 tool calls	`state.md`	Reorient. Right step? Scope crept?

>50 messages: re-read

state.md

plan.md

before every response. Files are truth, not memory.

以下文件是活跃的工作内存。在对话过程中需要反复阅读，而不仅仅是开始时读一次。

时机	读取文件	原因
任何执行步骤之前	`state.md` , `plan.md` , `progress.md`	确认当前步骤、变更记录、修复尝试、进度同步
编写修复代码之前	`decisions.md`	避免重复已失败的方案，检查三次失败规则
修改带有 `DECISION` 注释的代码之前	对应的 `decisions.md` 条目	修改前先理解原有决策的原因
规划或重新规划之前	`decisions.md` , `findings.md` , `findings/*`	基于已知事实制定规划
任何反思阶段之前	`plan.md` （验证标准）, `progress.md` , `verification.md`	对照书面标准进行评估，而非凭感觉
每调用10次工具之后	`state.md`	重新定位方向，确认是否在正确的步骤上，是否出现范围蔓延

对话消息超过50条：每次回复前都要重读

state.md

plan.md

。文件是事实依据，而非记忆。

Bootstrapping

引导启动

bash

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

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

, and removes the

.current_plan

pointer. The protocol CLOSE state (writing

summary.md

, auditing decision anchors) 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.

bash

node <skill-path>/scripts/bootstrap.mjs "goal"              # 创建新计划（向后兼容）
node <skill-path>/scripts/bootstrap.mjs new "goal"           # 创建新计划
node <skill-path>/scripts/bootstrap.mjs new --force "goal"   # 关闭活跃计划，创建新计划
node <skill-path>/scripts/bootstrap.mjs resume               # 为新会话生成重入摘要
node <skill-path>/scripts/bootstrap.mjs status               # 生成单行状态摘要
node <skill-path>/scripts/bootstrap.mjs close                # 关闭计划（保留计划目录）
node <skill-path>/scripts/bootstrap.mjs list                 # 显示所有计划目录

如果存在活跃计划，

new

命令会拒绝执行——请使用

resume

、

close

或

--force

参数。

new

命令会确保

.gitignore

包含

plans/

——防止执行步骤提交时将计划文件纳入版本控制。

close

命令会将当前计划的发现/决策合并到统一文件中，更新

state.md

，并删除

.current_plan

指针。在运行

close

命令之前，Agent需要完成协议规定的关闭阶段操作（写入

summary.md

、审核决策锚点）。引导启动完成后→读取
{plan-dir}
中的所有文件（

state.md

plan.md

decisions.md

findings.md

progress.md

verification.md

），然后再执行其他操作。随后进入探索阶段。用户提供的上下文→首先写入

findings.md

。

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)
└── 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
    └── summary.md                 # Written at CLOSE

Templates:

references/file-formats.md

plans/
├── .current_plan                  # → 指向活跃计划目录的名称
├── FINDINGS.md                    # 所有计划的统一发现记录（关闭计划时合并）
├── DECISIONS.md                   # 所有计划的统一决策记录（关闭计划时合并）
└── plan_2026-02-14_a3f1b2c9/      # {plan-dir}
    ├── state.md                   # 当前状态 + 转换日志
    ├── plan.md                    # 动态更新的计划文档（每次迭代都会重写）
    ├── decisions.md               # 仅追加的决策/转向日志
    ├── findings.md                # 发现内容摘要 + 索引
    ├── findings/                  # 详细的发现文件（子Agent写入此处）
    ├── progress.md                # 已完成 vs 待完成任务
    ├── verification.md            # 每次反思阶段的验证结果
    ├── checkpoints/               # 风险变更前的快照
    └── summary.md                 # 关闭阶段写入

模板文件：

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.

File	EXPLORE	PLAN	EXECUTE	REFLECT	RE-PLAN	CLOSE
state.md	W	W	R+W	W	W	W
plan.md	—	W	R+W	R	R	R
decisions.md	—	R+W	R	R+W	R+W	R
findings.md	W	R	—	R	R+W	R
findings/*	W	R	—	R	R+W	R
progress.md	—	W	R+W	R+W	W	R
verification.md	—	W	W	W	R	R
checkpoints/*	—	—	W	R	R	—
summary.md	—	—	—	—	—	W
plans/FINDINGS.md	R	R	—	—	R	W(merge)
plans/DECISIONS.md	R	R	—	—	R	W(merge)

R = 仅可读 | W = 可更新（隐含读取+写入） | R+W = 独立的读取和写入操作 | — = 禁止操作（当前状态下不应触碰）。

写前读规则：在写入/覆盖计划文件之前，必须先读取该文件——即使是引导启动后的第一次更新也不例外。Claude Code的写入工具会拒绝写入当前会话中未读取过的文件。此规则适用于下表中所有W和R+W的单元格。

文件	探索	规划	执行	反思	重新规划	关闭
state.md	W	W	R+W	W	W	W
plan.md	—	W	R+W	R	R	R
decisions.md	—	R+W	R	R+W	R+W	R
findings.md	W	R	—	R	R+W	R
findings/*	W	R	—	R	R+W	R
progress.md	—	W	R+W	R+W	W	R
verification.md	—	W	W	W	R	R
checkpoints/*	—	—	W	R	R	—
summary.md	—	—	—	—	—	W
plans/FINDINGS.md	R	R	—	—	R	W(合并)
plans/DECISIONS.md	R	R	—	—	R	W(合并)

Per-State Rules

各状态规则

EXPLORE

探索阶段

Read
```
state.md
```
,
```
plans/FINDINGS.md
```
and
```
plans/DECISIONS.md
```
at start of EXPLORE for cross-plan context.
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.
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]
```
.

探索阶段开始时，读取
```
state.md
```
,
```
plans/FINDINGS.md
```
和
```
plans/DECISIONS.md
```
以获取跨计划上下文。
读取代码、使用grep、glob、搜索工具。一次聚焦一个问题。
每进行2次读取操作后，将内容写入
```
findings.md
```
+
```
findings/
```
。每次写入前必须先读取文件。
包含文件路径 + 代码调用链（例如
```
auth.rb:23
```
→
```
SessionStore#find
```
→
```
redis_store.rb:get
```
）。
即使你认为自己知道答案，也不要跳过探索阶段。
最低要求：
```
findings.md
```
中至少有3条索引化的发现，才能转换到规划阶段。发现内容必须涵盖：(1) 问题范围，(2) 受影响的文件，(3) 现有模式或约束条件。不足3条→继续探索。
使用任务子Agent并行开展研究。所有子Agent的输出→写入
```
{plan-dir}/findings/
```
目录下的文件。切勿仅依赖上下文结果。主Agent在子Agent写入后更新
```
findings.md
```
的索引——子Agent不得修改索引。命名规则：
```
findings/{topic-slug}.md
```
（短横线命名法，描述性名称——例如
```
auth-system.md
```
,
```
test-coverage.md
```
）。
对于复杂分析，使用“深度思考”/“极致思考”模式。
反思→探索的循环：追加到现有发现内容，不要覆盖。用
```
[CORRECTED iter-N]
```
标记修正内容。

PLAN

规划阶段

Gate check: read
```
state.md
```
,
```
plan.md
```
,
```
findings.md
```
,
```
findings/*
```
,
```
decisions.md
```
,
```
progress.md
```
,
```
verification.md
```
,
```
plans/FINDINGS.md
```
,
```
plans/DECISIONS.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, failure modes, risks, success criteria, verification strategy, complexity budget.
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.
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).
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.

准入检查：写入任何内容之前，必须读取
```
state.md
```
,
```
plan.md
```
,
```
findings.md
```
,
```
findings/*
```
,
```
decisions.md
```
,
```
progress.md
```
,
```
verification.md
```
,
```
plans/FINDINGS.md
```
,
```
plans/DECISIONS.md
```
。如果未读取→立即读取。无例外。如果
```
findings.md
```
中的索引化发现不足3条→返回探索阶段。
先写问题陈述——在设计步骤之前，在
```
plan.md
```
中写入：(1) 预期行为，(2) 不变量——必须始终保持为真的条件，(3) 边界处的边缘情况。如果无法清晰陈述问题→返回探索阶段。
写入
```
plan.md
```
：问题陈述、执行步骤、失败模式、风险、成功标准、验证策略、复杂度预算。
验证策略——针对每个成功标准，定义：要运行的测试/检查、要执行的命令、什么结果代表“通过”。写入
```
plan.md
```
的“验证策略”部分。如果计划没有可测试的标准→写入“N/A — 仅需人工审核”（证明你已检查过）。模板参见
```
references/file-formats.md
```
。
失败模式分析——针对计划中的每个外部依赖或集成点，回答：如果依赖变慢？返回无效数据？服务宕机？影响范围有多大？写入
```
plan.md
```
的“失败模式”部分。如果没有依赖→写入“未识别到依赖”（证明你已检查过）。
写入
```
decisions.md
```
：记录选定的方案及其原因（即使是第一个计划也必须记录）。权衡规则——每个决策都要表述为“选择X，代价是Y”。绝不推荐不说明代价的方案。
先读取再写入
```
verification.md
```
，使用初始模板（从成功标准填充验证标准表格，从验证策略填充方法，结果列为待填充）。
先读取再写入
```
state.md
```
+
```
progress.md
```
。
列出所有需要修改/创建的文件。如果无法列出→返回探索阶段。
计划中仅包含推荐的方案。替代方案→写入
```
decisions.md
```
。
等待用户明确批准。

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) → note in
```
state.md
```
, finish or revert current step, transition to REFLECT. Do NOT silently update findings during EXECUTE.

Add

# DECISION D-NNN

comments where needed (

references/decision-anchoring.md

步骤前检查清单在
```
state.md
```
中：重置所有复选框为
```
[ ]
```
，在开始步骤前逐个勾选为
```
[x]
```
。这是强制重读规则的文件化执行机制。
第一次执行迭代→创建
```
checkpoints/cp-000-iter1.md
```
（终极回退方案）。“Git状态”=变更前的提交哈希（恢复点）。
分步执行。每完成一步后通过步骤后检查门（见下文）。
风险变更前创建检查点（修改3个以上文件、共享模块、破坏性操作）。命名规则：
```
cp-NNN-iterN.md
```
（例如
```
cp-001-iter2.md
```
）。NNN在所有迭代中全局递增。
每成功完成一个步骤后提交：
```
[iter-N/step-M] 描述
```
。
如果出现问题→立即停止。最多尝试2次修复（自主限制）。每次修复必须遵循“先回退”原则。
不可逆操作（数据库迁移、外部API调用、服务配置、未跟踪文件删除）：在规划阶段的
```
plan.md
```
中标记步骤为
```
[IRREVERSIBLE]
```
。完整流程参见
```
references/code-hygiene.md
```
。
意外发现（行为与发现内容矛盾、未知依赖、错误假设）→在
```
state.md
```
中记录，完成或回退当前步骤，转换到反思阶段。执行阶段禁止悄悄更新发现内容。

在需要的地方添加

# DECISION D-NNN

注释（参见

references/decision-anchoring.md

）。

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

步骤后检查门（仅适用于成功完成的步骤——需全部满足才能进入下一步）

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

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

```
plan.md
```
——标记步骤为
```
[x]
```
，更新进度标记，调整复杂度预算
```
progress.md
```
——将任务从“待完成”移至“已完成”，设置下一个“进行中”任务
```
state.md
```
——更新步骤编号，追加到变更记录中

步骤失败时：跳过检查门。遵循自主限制规则（先回退，最多尝试2次）。

REFLECT

反思阶段

Read
```
plan.md
```
(criteria + verification strategy) +
```
progress.md
```
before evaluating.
Read
```
findings.md
```
+ relevant
```
findings/*
```
— check if discoveries during EXECUTE contradict earlier findings. Note contradictions in
```
decisions.md
```
.
Read
```
checkpoints/*
```
— know what rollback options exist before deciding next transition. Note available restore points in
```
decisions.md
```
if transitioning to RE-PLAN.
Cross-validate: every
```
[x]
```
in plan.md must be "Completed" in progress.md. Fix drift first.
Run verification — execute each check defined in 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.
Read
```
decisions.md
```
— check 3-strike patterns.
Compare against written criteria, not memory. Run 5 Simplification Checks (
```
references/complexity-control.md
```
).
Write
```
decisions.md
```
(what happened, learned, root cause) +
```
progress.md
```
+
```
state.md
```
.

Condition	→ Transition
All criteria verified PASS in `verification.md`	→ CLOSE
Failure understood, new approach clear	→ RE-PLAN
Unknowns need investigation, or findings contradicted	→ EXPLORE (update findings first)

评估前读取
```
plan.md
```
（验证标准+验证策略） +
```
progress.md
```
。
读取
```
findings.md
```
+ 相关的
```
findings/*
```
文件——检查执行过程中的发现是否与之前的发现矛盾。在
```
decisions.md
```
中记录矛盾点。
读取
```
checkpoints/*
```
——在决定下一步转换前，明确可用的回退选项。在
```
decisions.md
```
中记录可用的恢复点（如果转换到重新规划阶段）。
交叉验证：
```
plan.md
```
中所有标记为
```
[x]
```
的步骤必须在
```
progress.md
```
中对应为“已完成”。先修正不一致的地方。
执行验证——按照验证策略执行每个检查。读取
```
verification.md
```
，然后记录结果：验证标准、方法、命令/操作、结果（通过/失败）、证据（输出摘要或日志引用）。模板参见
```
references/file-formats.md
```
。
读取
```
decisions.md
```
——检查三次失败模式。
对照书面标准评估，而非凭记忆。运行5项简化检查（
```
references/complexity-control.md
```
）。
写入
```
decisions.md
```
（发生的情况、经验总结、根本原因） +
```
progress.md
```
+
```
state.md
```
。

条件	转换方向
`verification.md` 中所有验证标准均通过	→ 关闭
已理解失败原因，且明确更优方案	→ 重新规划
存在未知问题需要调查，或发现内容存在矛盾	→ 探索（先更新发现内容）

RE-PLAN

重新规划阶段

Read
```
decisions.md
```
,
```
findings.md
```
, relevant
```
findings/*
```
.
Read
```
checkpoints/*
```
— decide keep vs revert. Default: if unsure, revert to latest checkpoint. See
```
references/code-hygiene.md
```
for full decision framework.
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.
Write
```
decisions.md
```
: log pivot + mandatory Complexity Assessment.
Write
```
state.md
```
+
```
progress.md
```
(mark failed items, note pivot).
Present options to user → get approval → transition to PLAN.

读取
```
decisions.md
```
,
```
findings.md
```
, 相关的
```
findings/*
```
文件。
读取
```
checkpoints/*
```
——决定保留还是回退。默认规则：如果不确定，回退到最新的检查点。完整决策框架参见
```
references/code-hygiene.md
```
。
如果之前的发现被证明错误或不完整→更新
```
findings.md
```
+
```
findings/*
```
文件，添加修正内容。标记修正：
```
[CORRECTED iter-N]
```
+ 变更内容及原因。追加内容，不要删除原始文本。
写入
```
decisions.md
```
：记录转向操作 + 强制复杂度评估。
写入
```
state.md
```
+
```
progress.md
```
（标记失败任务，记录转向）。
向用户呈现选项→获得批准→转换到规划阶段。

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× → RE-PLAN 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

失败后的默认应对方式是简化，而非添加内容。参见

references/complexity-control.md

。

先回退原则——出现问题时：(1) 停止 (2) 回退？(3) 删除？(4) 单行修复？(5) 以上都不行→反思。 10行规则——修复需要新增超过10行代码→这不是有效的修复→反思。 三次失败规则——同一区域连续失败3次→采用完全不同的方案重新规划。回退到覆盖该区域的检查点。 复杂度预算——在

plan.md

中跟踪：新增文件数0/3，新增抽象层0/2，代码行数净零目标。 禁止操作：嵌套包装器、配置开关、复制粘贴、异常吞噬、类型逃逸、适配器、“临时” workaround。 终极方案——迭代次数达到5次 + 代码膨胀超过初始范围的2倍→建议完全回退到

cp-000

（或用户同意的更晚的检查点）。否则谨慎继续。参见

references/complexity-control.md

。

Autonomy Leash (CRITICAL)

自主限制（至关重要）

When a step fails during EXECUTE:

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

Track attempts in

state.md

. Resets on: user direction, new step, or RE-PLAN. No exceptions. Unguided fix chains derail projects.

执行阶段步骤失败时：

最多尝试2次修复——每次修复必须遵循先回退原则 + 10行规则。
两次尝试均失败→完全停止。禁止第三次修复，禁止悄悄改用替代方案，禁止跳过当前步骤。
将未提交的变更回退到最近的干净提交。在向用户汇报前，代码库必须处于已知的良好状态。
汇报内容：步骤预期目标、实际发生情况、两次尝试的内容、对根本原因的猜测、可用的回退检查点。
转换→反思阶段。在
```
state.md
```
中记录触发自主限制。等待用户指令。

在

state.md

中跟踪尝试次数。当用户给出新指令、进入新步骤或重新规划时，重置尝试次数。 无例外。无指导的修复链会导致项目偏离轨道。

Code Hygiene (CRITICAL)

代码卫生（至关重要）

Failed code must not survive. Track changes in change manifest in

state.md

. Failed step → revert all uncommitted. RE-PLAN → explicitly decide keep vs revert. Codebase must be known-good before any PLAN. See

references/code-hygiene.md

失败的代码不得留存。在

state.md

的变更记录中跟踪所有变更。步骤失败→回退所有未提交的变更。重新规划→明确决定保留还是回退变更。在任何规划阶段之前，代码库必须处于已知的良好状态。参见

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

失败迭代的代码带有不可见的上下文信息。在影响点添加

# DECISION D-NNN

注释——说明不应做什么及原因。关闭阶段审核这些锚点。参见

references/decision-anchoring.md

。

Iteration Limits

迭代限制

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

Iteration 6+: hard STOP. Going in circles? Harder than scoped? Break into smaller tasks.

迭代次数在规划→执行阶段递增。迭代0=仅探索（规划前阶段）。第一次正式迭代=迭代1。

迭代6+：强制停止。是否在循环往复？任务比预期更难？拆分为更小的任务。

Recovery from Context Loss

上下文丢失恢复

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).
```
plans/.current_plan
```
→ plan dir name
```
state.md
```
→ where you are
```
plan.md
```
→ current plan
```
decisions.md
```
→ what was tried / failed
```
progress.md
```
→ done vs remaining
```
findings.md
```
+
```
findings/*
```
→ discovered context
```
checkpoints/*
```
→ available rollback points and their git hashes
```
plans/FINDINGS.md
```
+
```
plans/DECISIONS.md
```
→ cross-plan context from previous plans
Resume from current state. Never start over.

如果
```
plans/.current_plan
```
丢失或损坏：运行
```
bootstrap.mjs list
```
查找计划目录，然后重新创建指针：
```
echo "plan_YYYY-MM-DD_XXXXXXXX" > plans/.current_plan
```
（替换为实际的目录名称）。
```
plans/.current_plan
```
→ 计划目录名称
```
state.md
```
→ 当前所处状态
```
plan.md
```
→ 当前计划
```
decisions.md
```
→ 已尝试的方案/失败的内容
```
progress.md
```
→ 已完成 vs 待完成任务
```
findings.md
```
+
```
findings/*
```
→ 已发现的上下文
```
checkpoints/*
```
→ 可用的回退点及其Git哈希
```
plans/FINDINGS.md
```
+
```
plans/DECISIONS.md
```
→ 来自之前计划的跨计划上下文
从当前状态恢复，切勿从头开始。

Git Integration

Git集成

EXPLORE/PLAN/REFLECT/RE-PLAN: no commits.
EXECUTE: commit per successful step
```
[iter-N/step-M] desc
```
. Failed step → revert uncommitted.
RE-PLAN: 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.

探索/规划/反思/重新规划阶段：禁止提交。
执行阶段：每成功完成一个步骤提交一次，格式为
```
[iter-N/step-M] 描述
```
。步骤失败→回退未提交的变更。
重新规划阶段：如果成功提交的内容符合新计划则保留，否则使用
```
git checkout <checkpoint-commit> -- .
```
回退。禁止保留部分变更。在
```
decisions.md
```
中记录选择。
关闭阶段：最终提交 + 打标签。

User Interaction

用户交互

State	Behavior
EXPLORE	Ask focused questions, one at a time. Present findings.
PLAN	Present plan. Wait for approval. Re-present if modified.
EXECUTE	Report per step. Surface surprises. Ask before deviating.
REFLECT	Show expected vs actual. Propose: continue, re-plan, or close.
RE-PLAN	Reference decision log. Explain pivot. Get approval.

状态	行为
探索	一次提出一个聚焦的问题，呈现发现内容。
规划	呈现规划方案，等待批准。修订后重新呈现。
执行	按步骤汇报进度，及时反馈意外情况。偏离计划前需询问用户。
反思	对比预期与实际结果，提出建议：继续、重新规划或关闭。
重新规划	参考决策日志，解释转向原因，获得用户批准。

When NOT to Use

不适用场景

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

简单的单文件变更、解决方案明确的任务、已知根本原因的Bug，或“直接做”的任务。

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/file-formats.md
```
— 所有
```
{plan-dir}
```
文件的模板
```
references/complexity-control.md
```
— 反复杂度协议、禁止模式
```
references/code-hygiene.md
```
— 变更记录、回退流程
```
references/decision-anchoring.md
```
— 在代码中锚定决策的时机与方法