iterate-plan

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Iterate Plan

迭代计划

Revise one existing implementation plan in place. The output remains a plan: inspect the repository and edit the artifact, but leave implementation work to the implementation phase.

就地修订一份现有实施计划。输出仍是一份计划：检查仓库并编辑产物，但将实施工作留到实施阶段。

Steps

步骤

1. Establish the revision set

1. 确定修订范围

Resolve exactly one target plan and all of its context:

Use the plan path supplied by the user or already established in the conversation. If it is absent, inspect the active
```
.agent-work/tasks/<task>/
```
directory. Use a symlink-aware listing such as
```
ls -La
```
; task directories may be symlinks.
Read the entire plan, every user-supplied file, and every artifact in that task directory. Include
```
ticket.md
```
or
```
task.md
```
, research, design discussion, PRD or TDD, and structure outline files when present.
Inventory each requested change from the user's message and any supplied feedback file. Record its source, the affected plan section, and whether it states desired behavior, alleges a repository fact, or asks for a decision.
If the input contains an inline
```
<comments>
```
block, names artifact comments, relies on a ticket/comment file, or identifies only the plan without giving feedback, read feedback and decisions before classifying or acting on those items.

If no target can be distinguished among multiple plan files, ask the user to identify it and stop. If there is a target but no revision instruction or feedback, ask what they want changed and stop.

This step is complete only when one plan is selected, every available task artifact has been read, and every feedback item has a source, affected section, classification, and requested outcome or explicit unknown.

确定唯一的目标计划及其全部上下文：

使用用户提供的计划路径，或对话中已经确定的路径。如果不存在，检查当前生效的
```
.agent-work/tasks/<task>/
```
目录。使用能够感知符号链接的列表命令，例如
```
ls -La
```
；任务目录可能是符号链接。
阅读完整计划、用户提供的所有文件，以及该任务目录中的所有产物。包括
```
ticket.md
```
或
```
task.md
```
、研究资料、设计讨论、PRD 或 TDD，以及存在时的结构大纲文件。
清点用户消息和任何已提供反馈文件中的每项请求变更。记录其来源、受影响的计划章节，以及它是在陈述期望行为、断言仓库事实，还是要求作出决定。
如果输入包含内嵌
```
<comments>
```
块、提到产物评论、依赖 ticket 或 comment 文件，或者只指定了计划而未提供反馈，请先阅读反馈与决策，再对这些项进行分类或处理。

如果存在多个计划文件且无法确定唯一目标，请要求用户指定计划并停止。如果存在目标计划，但没有修订指示或反馈，请询问用户希望更改的内容并停止。

只有在一个计划已选定、所有可用任务产物均已读取，并且每条反馈项都记录了来源、受影响章节、分类以及请求结果或明确标记为未知时，此步骤才算完成。

2. Revalidate the plan against the repository

2. 根据仓库重新验证计划

Treat the repository as the source of truth for current implementation facts. Inspect the current branch and

HEAD

, then verify:

every path and symbol named by the feedback;
every path, symbol, dependency, configuration key, and test target the proposed revision will retain or introduce;
each code example against current APIs, types, naming, and nearby implementation patterns;
each automated verification command against current scripts, tooling, and test layout;
phase ordering against real dependencies between the planned changes.

User feedback controls desired behavior; repository evidence controls claims about what exists now. When they conflict, preserve the desired outcome and repair the implementation route. Prefer stable symbol or section anchors over stale line numbers.

This step is complete only when every retained or proposed implementation pointer has current evidence, and every contradictory or unverifiable claim is listed for disposition rather than silently copied into the plan.

将仓库视为当前实现事实的来源。检查当前分支和

HEAD

，然后验证：

反馈中提到的每个路径和符号；
拟议修订将保留或引入的每个路径、符号、依赖项、配置键和测试目标；
每段代码示例与当前 API、类型、命名及附近实现模式的一致性；
每条自动化验证命令与当前脚本、工具和测试布局的一致性；
阶段顺序与计划变更之间实际依赖关系的一致性。

用户反馈决定期望行为；仓库证据决定关于当前状态的事实性陈述。当二者冲突时，保留期望结果并修正实现路径。优先使用稳定的符号或章节锚点，而不是过时的行号。

只有当每个保留或拟议的实现指针都有当前证据支持，并且每项矛盾或无法验证的声明都已列出处置方式，而不是被静默复制到计划中时，此步骤才算完成。

3. Reconcile feedback and decisions

3. 核对反馈与决定

Build a revision ledger with one disposition for every feedback item:

apply as stated

already satisfied

apply with evidence-backed correction

, or

decision required

Use this authority order:

the user's latest explicit direction for desired behavior and scope;
the existing plan;
structure outline;
TDD, then design discussion;
research;
ticket or task description.

Repository evidence may correct factual statements at any level. It does not choose among materially different product, scope, or architecture outcomes on the user's behalf.

When a real decision remains, ask one question that presents the viable options, concrete tradeoffs, and a recommendation, then stop. Resume from the ledger after the answer. Straightforward corrections and evidence-backed repairs proceed without a confirmation round.

This step is complete only when every feedback item has a defensible disposition and no unanswered decision can change the plan's scope, architecture, or dependency order.

建立修订台账，为每条反馈项指定一种处置方式：

apply as stated

、

already satisfied

、

apply with evidence-backed correction

或

decision required

。

使用以下权威顺序：

用户对于期望行为和范围的最新的明确指示；
现有计划；
结构大纲；
TDD，然后是设计讨论；
研究资料；
ticket 或任务描述。

仓库证据可以在任何层级修正事实性陈述，但不会代替用户在实质不同的产品、范围或架构结果之间作出选择。

如果仍存在真正需要决定的事项，请提出一个问题，列出可行选项、具体权衡和建议，然后停止。收到答复后，从台账继续处理。直接可修正的问题和有证据支持的修复无需确认环节。

只有当每条反馈项都有可辩护的处置方式，并且任何尚未回答的决定都不会改变计划范围、架构或依赖顺序时，此步骤才算完成。

4. Revise the plan in place

4. 就地修订计划

Edit the existing plan at the same path. Preserve its frontmatter and established section shape unless the feedback explicitly changes the plan format. Keep these invariants:

Each phase is independently implementable and testable, ordered after its prerequisites.
Each change names the exact file and current symbol or insertion point, explains the intended behavior, and includes accurate code or diff examples where they remove implementation ambiguity.
Automated success criteria are runnable commands with an observable passing result.
Manual criteria appear only when human observation or judgment is material; they state the action and expected result. A phase with manual criteria pauses for confirmation before the next phase.
Tests follow repository patterns discovered during revalidation and cover the behavior changed by that phase.
Overview, current state, desired state, approach, exclusions, phases, and success criteria agree with one another.
Every feedback item marked
```
apply as stated
```
or
```
apply with evidence-backed correction
```
changes all affected sections, not only the sentence that attracted the comment.

When the plan records completed work, preserve the recorded outcome. If new evidence makes completed work obsolete or unsafe, annotate the conflict and add a later remediation or rollback step instead of rewriting history.

Update an existing revision-history section when present. Otherwise add a compact revision note only when it is needed to explain a changed decision or invalidated completed work. Use four-backtick outer fences when a Markdown example contains triple-backtick fences.

After the content edit, perform only the comment replies or state changes that the user explicitly authorized. Process them one thread at a time, then re-read each affected thread to confirm its requested state. Applying comment content does not imply authority to reply, resolve, reopen, delete, or restore.

This step is complete only when every applied disposition is reflected everywhere it propagates, every remaining step is executable from current repository state, dependency order is valid, and every phase has an observable completion signal.

在同一路径编辑现有计划。除非反馈明确要求改变计划格式，否则保留其 frontmatter 和既有章节结构。保持以下不变量：

每个阶段都可以独立实施和测试，并排列在其前置条件之后。
每项变更都指定准确文件以及当前符号或插入位置，解释预期行为，并在有助于消除实施歧义时提供准确的代码或 diff 示例。
自动化成功标准是可运行的命令，并具有可观察的通过结果。
仅当人工观察或判断具有实质意义时才设置人工标准；标准应说明操作及预期结果。包含人工标准的阶段会在进入下一阶段前暂停并等待确认。
测试遵循重新验证期间发现的仓库模式，并覆盖该阶段发生变更的行为。
概览、当前状态、期望状态、方案、排除项、阶段和成功标准彼此一致。
每条标记为
```
apply as stated
```
或
```
apply with evidence-backed correction
```
的反馈项都会影响所有相关章节，而不只是引发评论的那句话。

当计划记录了已完成工作时，保留所记录的结果。如果新证据表明已完成工作已经过时或不安全，则标注冲突，并添加后续修复或回滚步骤，而不是重写历史。

如果存在修订历史章节，则更新该章节。否则，仅在需要解释已变更的决定或已失效的已完成工作时，添加简短的修订说明。当 Markdown 示例包含三重反引号代码围栏时，使用四反引号作为外层围栏。

完成内容编辑后，仅执行用户明确授权的评论回复或状态变更。逐个线程处理，然后重新阅读每个受影响的线程，以确认其请求状态已达成。应用评论内容并不意味着获得回复、解决、重新打开、删除或恢复评论的权限。

只有当每项已应用的处置方式都反映在所有受影响位置、剩余步骤均可基于当前仓库状态执行、依赖顺序有效，并且每个阶段都有可观察的完成信号时，此步骤才算完成。

5. Audit the finished artifact

5. 审计最终产物

Read the revised plan from beginning to end and compare it with the revision ledger and repository evidence. Check that:

every feedback item has the recorded disposition and no requested change was dropped;
frontmatter still identifies the task, repository, current branch, and revalidated
```
HEAD
```
accurately;
retained paths, symbols, examples, tests, and commands are current;
the phase sequence contains no circular, missing, or reversed dependency;
code fences and local links are valid;
placeholders remain only where the implementer must supply a runtime value;
the revision introduced no contradiction between narrative, examples, and success criteria.
every authorized comment action reached its requested observable state and every unrequested comment state remained unchanged.

If the ledger contains

already satisfied

apply with evidence-backed correction

, the final plan itself must make the relevant truth clear; do not add process commentary merely to prove that feedback was reviewed.

This step is complete only after the reread accounts for every ledger item and every check above passes or the workflow has stopped on one precise user decision.

从头到尾阅读修订后的计划，并将其与修订台账和仓库证据进行比较。检查：

每条反馈项都有记录的处置方式，且没有遗漏任何请求变更；
frontmatter 仍能准确标识任务、仓库、当前分支和重新验证后的
```
HEAD
```
；
保留的路径、符号、示例、测试和命令均为当前有效状态；
阶段顺序不存在循环依赖、缺失依赖或顺序倒置的依赖；
代码围栏和本地链接均有效；
占位符仅保留在实施者必须提供运行时值的位置；
修订未在叙述、示例和成功标准之间引入矛盾；
每项已授权的评论操作都达到了请求的可观察状态，且每项未获授权的评论状态都保持不变。

如果台账包含

already satisfied

或

apply with evidence-backed correction

，最终计划本身必须清楚说明相关事实；不要仅为证明已审阅反馈而添加过程性说明。

只有当重新阅读已涵盖每条台账项，并且上述每项检查均已通过，或者工作流已因一个明确的用户决定而停止时，此步骤才算完成。

6. Route the handoff

6. 路由交接

After the content audit and comment-operation reconciliation:

Read
```
.agent-work/workspace.json
```
and
```
.agent-work/workspace.local.json
```
when present. For
```
disabled
```
, values explicitly set in the local file override the shared file.
Run
```
git rev-parse --git-dir
```
and
```
git status --short
```
. Inventory every tracked, staged, and untracked path before any branch operation.
Select exactly one branch below, in order:
- If the git directory contains
```
.git/worktrees/
```
  , read the in-worktree final answer.
- Otherwise, if effective
```
disabled
```
  is
```
true
```
  , check out the task branch, defaulting its name to the task-directory slug. Reuse that branch if it already exists; create it if it does not. Attempt the checkout only when it preserves every inventoried change. If safety cannot be established or the checkout conflicts, leave the current branch and worktree untouched and read the pending final answer. Otherwise read the disabled-workspace final answer.
- Otherwise, read the worktree-setup final answer.
If checkout changed the branch, synchronize the plan's
```
branch
```
and
```
sha
```
frontmatter with the checked-out branch and its
```
HEAD
```
, then re-read that frontmatter.
Substitute the actual plan path, checked-out branch, and artifact permalink. Include the permalink only when the host supplied one.
If any authorized comment action failed, select the pending template even when no checkout was needed and list each failed thread operation. Respond with the selected template and no additional summary.

This step is complete only when one mode was selected from observed configuration and git state, every pre-existing change is preserved, any branch checkout either succeeded safely or produced the pending handoff, all authorized comment operations are reconciled, and every value in the response is factual.

完成内容审计和评论操作核对后：

存在时，读取
```
.agent-work/workspace.json
```
和
```
.agent-work/workspace.local.json
```
。对于
```
disabled
```
，本地文件中显式设置的值覆盖共享文件中的值。
运行
```
git rev-parse --git-dir
```
和
```
git status --short
```
。在任何分支操作之前，清点所有已跟踪、已暂存和未跟踪的路径。
按以下顺序选择且仅选择一种处理方式：
- 如果 Git 目录包含
```
.git/worktrees/
```
  ，阅读 worktree 中的最终答复。
- 否则，如果有效的
```
disabled
```
  为
```
true
```
  ，则 checkout 任务分支，其名称默认使用任务目录的 slug。如果该分支已经存在则复用，否则创建。只有在能够保留所有已清点变更时，才尝试 checkout。如果无法确保安全或 checkout 发生冲突，则不触碰当前分支和 worktree，并阅读待处理最终答复。否则，阅读 disabled-workspace 最终答复。
- 否则，阅读 worktree-setup 最终答复。
如果 checkout 切换了分支，则将计划的
```
branch
```
和
```
sha
```
frontmatter 与已 checkout 的分支及其
```
HEAD
```
同步，然后重新阅读该 frontmatter。
替换为实际计划路径、已 checkout 的分支和产物 permalink。仅当主机提供 permalink 时才包含它。
如果任何已授权的评论操作失败，即使无需 checkout，也应选择待处理模板，并列出每个失败的线程操作。使用所选模板作答，不附加其他摘要。

只有当根据观察到的配置和 Git 状态选定了一种模式、所有既有变更均得到保留、分支 checkout 要么安全成功、要么产生待处理交接、所有已授权评论操作均已核对，并且答复中的每个值都符合事实时，此步骤才算完成。