Back to Details

iterate-implementation

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Iterate an implementation

迭代已有实现

Treat follow-up feedback as a reconciliation job: recover the accepted intent, prove the current behavior, and close every reported or discovered gap without restarting sound work.
将后续反馈视为一项对账工作：找回已确认的意图，证明当前行为，并在不重启合理工作的前提下，弥合所有已报告或已发现的缺口。

1. Establish the workspace and authority

1. 确定工作区与依据

Resolve the repository root, branch, worktree identity, and current status before changing files. Use 
git rev-parse --show-toplevel
and 
git rev-parse --git-dir
; when 
.agent-work/workspace.json
or 
.agent-work/workspace.local.json
exists, inspect both and let the local file override the shared file. Stay in the current checkout. A linked worktree, an ordinary checkout with workspace creation disabled, and an ordinary checkout with workspace creation enabled are all valid iteration locations; iteration itself does not create or switch branches or worktrees. If the requested work belongs to a different checkout, stop with the exact mismatch and the target path or branch that must be selected.
Locate the task directory from a supplied path or ticket ID. Under 
.agent-work/tasks/
, inspect directory entries with symlink-aware commands such as 
ls -La
; task directories may be symlinks. Read the complete plan and every artifact needed to interpret it: ticket or task, research, design discussion, PRD/TDD, structure outline, review comments, and relevant logs. If no plan exists, derive authority from the remaining artifacts. When artifacts conflict, use this precedence:
plan > structure outline > TDD > PRD > design discussion > research > ticket
Repository instructions and the user's current explicit direction still govern the work. Record any conflict rather than silently blending incompatible requirements.
Identify the implementation boundary from an explicit commit, phase handoff, or trustworthy merge base. Inspect every staged, unstaged, untracked, and committed change since that boundary. Separate iteration-owned changes from unrelated user work.
This step is complete when the task sources, authority order, implementation boundary, current phase, worktree mode, and unrelated changes are all known or each missing item is named as an uncertainty.
在更改文件前，确定仓库根目录、分支、worktree 标识和当前状态。使用 
git rev-parse --show-toplevel
和 
git rev-parse --git-dir
；当存在 
.agent-work/workspace.json
或 
.agent-work/workspace.local.json
时，检查这两个文件，并让本地文件覆盖共享文件中的值。始终留在当前 checkout 中。linked worktree、禁用 workspace 创建的普通 checkout，以及启用 workspace 创建的普通 checkout 都是有效的迭代位置；迭代本身不会创建或切换分支与 worktree。如果请求的工作属于另一个 checkout，则停止操作，报告确切的不匹配信息，以及必须选择的目标路径或分支。
从给定路径或 ticket ID 定位任务目录。在 
.agent-work/tasks/
下，使用能够感知符号链接的命令（如 
ls -La
）检查目录项；任务目录可能是符号链接。完整阅读 plan 及解释它所需的所有工件：ticket 或 task、research、design discussion、PRD/TDD、structure outline、review comments 和相关日志。如果不存在 plan，则根据其余工件确定依据。当工件之间发生冲突时，使用以下优先级：
plan > structure outline > TDD > PRD > design discussion > research > ticket
仓库指令和用户当前的明确指示仍对工作具有约束力。记录任何冲突，不要悄悄混合不兼容的要求。
通过明确的 commit、阶段交接或可信的 merge base 确定实现边界。检查自该边界以来的每项已暂存、未暂存、未跟踪和已提交变更。将本次迭代负责的变更与无关的用户工作区分开来。
完成此步骤的条件是：任务来源、依据顺序、实现边界、当前阶段、worktree 模式以及无关变更均已明确，或者每项缺失信息都被列为不确定项。

2. Build the feedback ledger

2. 建立反馈台账

Inventory every input from the current request, issue or review comments, referenced files and examples, failing checks, logs, prior agent handoffs, incomplete artifact items, and visible implementation deviations. Give each item an ID and record:
  • the reported observation or requested outcome;
  • its source and concrete evidence;
  • expected behavior and affected scope;
  • current disposition: 
    pending
    , 
    needs-input
    , 
    rejected-with-evidence
    , 
    deferred-by-user
    , 
    repairing
    , 
    awaiting-verification
    , or 
    complete
    .
Verify user-supplied paths, snippets, and causal claims against the repository or runtime evidence. Preserve the requested outcome while correcting inaccurate details in the repair plan.
This step is complete when every distinct input maps to exactly one ledger item and every item has evidence, a disposition, and a next action.
清点当前请求、issue 或 review comments、引用的文件和示例、失败的检查项、日志、此前的 agent 交接、未完成的工件项，以及可见的实现偏差等所有输入。为每项输入分配 ID，并记录：
  • 报告的现象或请求的结果；
  • 来源和具体证据；
  • 预期行为和影响范围；
  • 当前处置状态：
    pending
    、
    needs-input
    、
    rejected-with-evidence
    、
    deferred-by-user
    、
    repairing
    、
    awaiting-verification
    或 
    complete
    。
根据仓库或运行时证据验证用户提供的路径、代码片段和因果判断。在修复方案中纠正不准确的细节，同时保留请求的结果。
完成此步骤的条件是：每项不同输入都恰好对应一个台账项，并且每项都有证据、处置状态和下一步操作。

3. Diagnose each open item

3. 诊断每个未结项

For a defect, reproduce the failure with the narrowest reliable check, then trace it to a root cause. Inspect relevant logs, data stores, and running services when the behavior depends on runtime state. For a requested change, compare the actual behavior with the authoritative artifact and surrounding implementation. Inspect the specific locations named by the user plus the callers, data paths, tests, configuration, and generated surfaces needed to bound impact.
Classify implementation differences as one of:
  • planned and present;
  • intentional deviation with a recorded reason;
  • accidental deviation requiring repair;
  • necessary addition absent from the artifact;
  • planned work still missing.
When local evidence cannot establish the cause, request the smallest missing input. If runtime evidence is required, add only scoped instrumentation that the repository can safely carry, provide exact reproduction steps, and pause until results arrive. When two materially different solutions remain viable, present the verified tradeoff and ask the user to choose. Otherwise select the smallest coherent repair that satisfies accepted intent.
This step is complete when every open ledger item has a confirmed cause and repair target, a documented evidence-backed rejection, an approved deferral, or one precise blocking question.
对于缺陷，使用最窄且可靠的检查复现故障，然后追踪至根因。当行为依赖运行时状态时，检查相关日志、数据存储和正在运行的服务。对于变更请求，将实际行为与权威工件及周边实现进行比较。除用户指定的具体位置外，还要检查调用方、数据路径、测试、配置，以及界定影响范围所需的生成内容。
将实现差异归为以下类别之一：
  • 符合计划且已经存在；
  • 已记录原因的有意偏差；
  • 需要修复的意外偏差；
  • 工件中未体现但确有必要的补充；
  • 仍未完成的计划工作。
如果本地证据无法确定原因，请请求最少量的缺失输入。如果必须获取运行时证据，仅添加仓库能够安全承载且范围明确的检测代码，提供准确的复现步骤，并暂停工作直至结果到达。当仍有两个实质不同的可行方案时，展示经过验证的权衡并请用户选择。否则，选择满足已确认意图的最小且连贯的修复方案。
完成此步骤的条件是：每个未结台账项都有已确认的原因和修复目标、有证据支持的拒绝结论、已批准的延期，或一个精确的阻塞问题。

4. Route implementation work

4. 分配实现工作

Keep surgical repairs in the current iteration. Treat an entirely unstarted phase or a coherent follow-on feature as implementation work and delegate it through the host's agent mechanism when available:
  • use 
    implementer-agent
    when a detailed plan is authoritative;
  • use 
    outline-implementer-agent
    when the structure outline is authoritative and no plan exists.
Give the agent the phase, artifact paths, feedback IDs, ownership boundary, and required automated checks. Ask it to stop after that bounded work and report changes, verification, deviations, and manual checks. Keep the prompt concise because the agent reads the artifacts itself. If helper agents are unavailable, execute the same bounded assignment locally.
Review the agent's result and actual diff before accepting any claim. The orchestrator retains ownership of the ledger, integration, artifact state, and final verification.
This step is complete when every open item has one owner and each delegated assignment has a non-overlapping boundary and an explicit verification target.
将小范围修复保留在当前迭代中。对于完全尚未启动的阶段或连贯的后续功能，将其视为实现工作，并在可用时通过宿主的 agent 机制进行委派：
  • 当详细 plan 为权威依据时，使用 
    implementer-agent
    ；
  • 当 structure outline 为权威依据且不存在 plan 时，使用 
    outline-implementer-agent
    。
向 agent 提供阶段、工件路径、反馈 ID、所有权边界和必需的自动化检查。要求其在完成这项有界工作后停止，并报告变更、验证结果、偏差和手动检查。提示应保持简洁，因为 agent 会自行阅读工件。如果 helper agents 不可用，则在本地执行相同的有界任务。
在接受任何声明前，审查 agent 的结果和实际 diff。orchestrator 继续负责台账、集成、工件状态和最终验证。
完成此步骤的条件是：每个未结项都有明确的负责人，并且每项委派任务都具有互不重叠的边界和明确的验证目标。

5. Run the repair loop

5. 运行修复循环

Work one causally related item cluster at a time:
  1. Capture a failing test, reproduction, or other observable mismatch.
  2. Apply the smallest complete change that fixes the root cause and its necessary integration points.
  3. Run the focused check that proves the item changed from failing to passing.
  4. Inspect the resulting diff for collateral behavior and update the ledger.
If the focused check still fails, revise the diagnosis before adding another change. Preserve unrelated edits and follow repository conventions. When a Markdown file demonstrates fenced Markdown, make the outer fence longer than every nested fence. Keep temporary logging, fixtures, generated files, and compatibility shims only when they are intentional deliverables.
Repeat until every repairable item is 
awaiting-verification
or 
complete
. This step is complete only when no ledger item remains 
pending
or 
repairing
.
每次处理一个具有因果关联的项集群：
  1. 捕获失败的测试、复现步骤或其他可观察的不匹配。
  2. 应用能够修复根因及其必要集成点的最小完整变更。
  3. 运行聚焦检查，证明该项已从失败变为通过。
  4. 检查最终 diff 是否产生连带影响，并更新台账。
如果聚焦检查仍然失败，请在添加另一项变更之前重新审视诊断。保留无关编辑，并遵循仓库约定。当一个 Markdown 文件演示围栏 Markdown 时，使外层围栏比每个嵌套围栏更长。仅在临时日志、fixtures、生成文件和 compatibility shim 属于有意交付的成果时保留它们。
重复此过程，直至每个可修复项均为 
awaiting-verification
或 
complete
。只有当台账中不再存在 
pending
或 
repairing
项时，此步骤才算完成。

6. Verify the integrated result

6. 验证集成结果

Run verification in widening rings:
  1. focused regression checks for every repaired item;
  2. affected module or integration tests;
  3. repository-prescribed formatting, lint, type, build, and test commands relevant to the changed surface;
  4. manual checks required by the plan or by behavior that automation cannot observe.
Record the exact command or manual action and result against each ledger item. Distinguish a new regression from a reproducible pre-existing failure. A failed or unavailable check stays visible with its output, impact, and next action. Manual items become complete only after the user confirms them.
Re-read the authoritative artifacts and audit the entire implementation diff, not only the latest edits. Confirm that every planned item is present or explicitly disposed, every addition and deviation is explained, no repair contradicts a later artifact, and the remaining diff is intentional. Update implementation checkboxes only for work actually completed; update manual-verification checkboxes only from human confirmation. When an artifact integration supplies an optional permalink, preserve it for the handoff.
This step is complete when every ledger item has verification evidence, all required automated checks pass or have a documented unresolved disposition, every deviation is accounted for, and no temporary or unrelated change is attributed to the iteration.
按照逐步扩大的范围进行验证：
  1. 对每个已修复项运行聚焦回归检查；
  2. 运行受影响的模块测试或集成测试；
  3. 运行仓库规定且与变更范围相关的 formatting、lint、type、build 和 test 命令；
  4. 执行 plan 要求或自动化无法观察的行为所需的手动检查。
针对每个台账项记录准确的命令或手动操作及其结果。区分新引入的回归与可复现的既有失败。失败或无法执行的检查必须保持可见，并附上其输出、影响和下一步操作。只有在用户确认后，手动项才能标记为完成。
重新阅读权威工件，并审计整个实现 diff，而不只是最新编辑。确认每个计划项均已存在或得到明确处置，每项新增内容和偏差均已解释，没有修复与后续工件相矛盾，并且剩余 diff 均为有意变更。仅对实际完成的工作更新实现复选框；仅依据人工确认更新手动验证复选框。如果工件集成提供了可选的 permalink，请保留它以供交接。
完成此步骤的条件是：每个台账项都有验证证据，所有必需的自动化检查均通过或已有明确的未解决处置结论，每项偏差均已交代，并且没有将临时变更或无关变更归入本次迭代。

7. Hand off the iteration

7. 交接本次迭代

Read the iteration handoff contract whenever work completes, pauses for manual verification, or blocks on missing evidence or a decision. Select its status from the gates in that file and render the matching response with no additional sections.
Iteration is complete only when every feedback item is 
complete
, 
rejected-with-evidence
, or 
deferred-by-user
; all required automated checks pass; required manual verification is confirmed; artifact state matches the implementation; and the remaining diff is intentional. A commit or push is a separate action and occurs only when the user authorizes it.
每当工作完成、暂停等待手动验证，或因缺少证据或决策而阻塞时，阅读迭代交接契约。根据该文件中的门槛条件选择状态，并渲染匹配的响应，不添加其他章节。
只有当每个反馈项均为 
complete
、
rejected-with-evidence
或 
deferred-by-user
，所有必需的自动化检查均已通过，必需的手动验证已得到确认，工件状态与实现一致，并且剩余 diff 均为有意变更时，迭代才算完成。commit 或 push 属于独立操作，仅在用户授权时执行。