iterate-structure-outline

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Iterate a structure outline

迭代结构大纲

Revise the existing outline in place. Feedback changes the artifact, never starts implementation.

原地修订现有大纲。反馈用于修改产物，绝不启动实施。

1. Establish the request

1. 确定请求

If the invocation contains neither feedback nor an instruction to inspect artifact comments, ask:

text

I'm ready to iterate on the structure outline. What would you like to change? You can share feedback, point me to artifact comments, answer an open question, or ask me to rework the phase structure or verification.

Stop after asking. A bare invocation is not permission to invent revisions.

Resolve the task directory and outline path from the prompt or conversation. When only a directory is supplied, or the known artifact path is under

.agent-work/tasks/<task-slug>

, inspect that directory with

ls -La

; the path may be a symlink. Use that listing as the directory inventory rather than globbing or searching through

.agent-work/tasks

. If the task directory cannot be identified from available context, ask for the artifact path.

Read the outline and every prior workflow artifact in the task directory in full:

ticket.md

task.md

, completed research, design discussion, PRD, TDD, and any later planning artifact. Read every file or path cited by those artifacts or by the feedback when it can affect the revision. Research-question documents are superseded by completed research and are needed only when feedback explicitly concerns them.

Apply this precedence when sources conflict:

text

current user decision and verified evidence
  > structure outline
  > TDD
  > PRD
  > design discussion
  > completed research
  > ticket or task

This step is complete when the exact outline path is known and every source capable of changing the requested revision has been read.

如果调用中既没有反馈，也没有检查产物评论的指令，则询问：

text

我已准备好迭代结构大纲。你希望更改什么？你可以提供反馈、指向产物评论、回答未决问题，或让我重做阶段结构或验证方案。

询问后即停止。仅有调用本身并不表示可以自行构思修订内容。

从提示词或对话中确定任务目录和大纲路径。当只提供目录，或已知的产物路径位于

.agent-work/tasks/<task-slug>

下时，使用

ls -La

检查该目录；该路径可能是符号链接。使用该列表作为目录清单，而不是通过 glob 在

.agent-work/tasks

中搜索。如果无法从现有上下文确定任务目录，则询问产物路径。

完整阅读大纲以及任务目录中的每个先前工作流产物：

ticket.md

或

task.md

、已完成的研究、设计讨论、PRD、TDD，以及任何后续规划产物。阅读这些产物或反馈引用的每个文件或路径，只要其可能影响本次修订。研究问题文档已被完成的研究取代，只有当反馈明确涉及它们时才需要阅读。

当来源发生冲突时，采用以下优先级：

text

当前用户决策和已验证证据
  > 结构大纲
  > TDD
  > PRD
  > 设计讨论
  > 已完成的研究
  > 工单或任务

当确切的大纲路径已知，且所有可能影响所请求修订的来源均已阅读时，本步骤完成。

2. Inventory the feedback

2. 盘点反馈

Build a private checklist containing every discrete request, answer, correction, and comment. Keep comment state separate from document state: a comment can be incorporated in the outline while remaining open in the artifact system.

When feedback arrives as an artifact-comment block, a ticket file containing comments, or an instruction to fetch, reply to, or resolve comments, read feedback and comment handling before acting. Follow every comment thread, including replies and existing resolution markers.

Classify each checklist item as one of:

```
verify
```
— asserts something about the repository, dependency, or existing behavior;
```
decision
```
— records the user's chosen product or technical direction;
```
revision
```
— requests a direct structural or editorial change;
```
question
```
— remains open until the user or evidence supplies an answer;
```
comment-action
```
— requests a reply, resolution, reopening, or deletion in the artifact system.

This step is complete when every input has exactly one checklist entry, source, and required outcome.

建立一份私有清单，涵盖每一项独立请求、回答、修正和评论。将评论状态与文档状态分开：评论可以已纳入大纲，但在产物系统中仍保持打开状态。

当反馈以 artifact-comment 块、包含评论的 ticket 文件的形式出现，或要求获取、回复或解决评论时，先阅读反馈与评论处理，然后再采取行动。跟进每个评论线程，包括回复和已有的解决标记。

将每个清单项归类为以下一种：

```
verify
```
— 断言代码库、依赖或现有行为的某些情况；
```
decision
```
— 记录用户选择的产品或技术方向；
```
revision
```
— 要求直接进行结构或编辑层面的修改；
```
question
```
— 在用户或证据提供答案前保持未决；
```
comment-action
```
— 要求在产物系统中回复、解决、重新打开或删除评论。

当每项输入都恰好对应一个清单项、一个来源和一个所需结果时，本步骤完成。

3. Verify the change surface

3. 验证变更范围

Treat user decisions as authoritative choices and factual claims as hypotheses. Inspect the cited code and current repository patterns before changing paths, ownership, dependencies, signatures, or verification commands. Re-check prior research where repository state may have moved since it was written.

For deeper investigation, delegate bounded questions to the available specialists and wait for their results before editing:

```
codebase-locator
```
for ownership and file discovery;
```
codebase-analyzer
```
for implementation and dependency behavior;
```
codebase-pattern-finder
```
for analogous production and test patterns;
```
web-search-researcher
```
for external standards or practices;
a library researcher, when one is available, for dependency-specific questions.

Run independent investigations concurrently when possible. Use repository evidence for repository claims and primary sources for external claims. Record a disposition for every checklist item:

incorporate

already represented

decline with evidence

defer with owner

, or

needs user decision

This step is complete when every factual item has evidence and every checklist item has a defensible disposition.

将用户决策视为权威选择，将事实性陈述视为待验证假设。在更改路径、负责归属、依赖、签名或验证命令之前，检查所引用的代码和当前代码库模式。如果仓库状态可能自研究完成以来发生变化，应重新核查先前研究。

如需更深入的调查，请在编辑前将边界明确的问题委派给可用专家，并等待其返回结果：

```
codebase-locator
```
：确定负责归属和发现文件；
```
codebase-analyzer
```
：分析实现和依赖行为；
```
codebase-pattern-finder
```
：查找类似的生产代码和测试模式；
```
web-search-researcher
```
：调研外部标准或实践；
library researcher（如可用）：调研依赖相关问题。

尽可能并行开展相互独立的调查。对于代码库相关主张，使用代码库证据；对于外部主张，使用一手来源。为每个清单项记录处置结果：

incorporate

、

already represented

、

decline with evidence

、

defer with owner

或

needs user decision

。

当每项事实性内容都有证据，且每个清单项都有可辩护的处置结果时，本步骤完成。

4. Recompute the outline

4. 重新计算大纲

For any change that affects scope, phase boundaries, ordering, files, dependencies, tests, or validation, read outline revision rules and apply its complete audit. A local wording correction may stay local only when it cannot change those concerns.

Edit the existing outline at the same path. Preserve its frontmatter, filename, overall artifact format, and stable phase identity where the intended outcome remains unchanged. Repaint affected sections so the result reads as one current outline rather than a feedback log.

At minimum:

incorporate accepted scope changes into both the desired end state and What we're not doing;
incorporate answered questions into the relevant sections and remove them from Open Questions;
add newly exposed blocking questions to Open Questions;
update the implementation checklist, phase headings, change outlines, dependencies, and verification together;
preserve a completed phase only when its outcome and proof remain valid after the revision; reopen it when the new outline requires more work.

Keep the outline at header-file resolution: precise ownership, interfaces, data shapes, dependencies, and proof, with focused snippets only when they clarify structure. Use four-backtick outer fences when an example contains fenced Markdown.

This step is complete when every

incorporate

item appears in the artifact, every

already represented

item is still true, and no superseded answer remains as live guidance.

对于任何会影响范围、阶段边界、顺序、文件、依赖、测试或验证的变更，请阅读大纲修订规则并执行其完整审核。只有在局部措辞修正不可能影响上述事项时，才可将其保留为局部修改。

在同一路径编辑现有大纲。保留其 frontmatter、文件名、整体产物格式，以及在预期结果保持不变时的稳定阶段标识。重写受影响的章节，使结果呈现为一份当前的大纲，而不是反馈日志。

至少需要：

将已接受的范围变更纳入目标最终状态和我们不做什么；
将已回答的问题纳入相关章节，并从未决问题中移除；
将新发现的阻塞性问题加入未决问题；
同步更新实施清单、阶段标题、变更大纲、依赖关系和验证方式；
仅当已完成阶段的结果和证据在修订后仍然有效时才保留该阶段；当新大纲需要更多工作时，应重新打开该阶段。

将大纲保持在标题文件级粒度：明确负责归属、接口、数据结构、依赖关系和验证依据；仅在有助于澄清结构时使用聚焦的代码片段。当示例包含带围栏的 Markdown 时，使用四个反引号作为外层围栏。

当每个

incorporate

项都已出现在产物中，每个

already represented

项仍然成立，并且没有任何被取代的答案继续作为有效指导时，本步骤完成。

5. Audit readiness and comment actions

5. 审核就绪状态和评论操作

Re-read the rendered outline and check all of the following:

every requested item has its recorded disposition;
every desired-end-state requirement belongs to at least one phase;
every in-scope phase contribution traces back to a requirement or verified constraint;
phase order is acyclic and each prerequisite exists before its consumer;
every phase can be verified at its own boundary without work from a later phase;
each changed file, interface, migration, and test responsibility appears in the correct phase;
automated checks use real repository commands and manual checks cover only irreducible human judgment;
the implementation overview and phase sections have the same count, titles, order, and completion state;
open questions, unresolved feedback, and unresolved artifact comments are explicit.

Execute authorized comment replies or state changes only after their corresponding artifact edits and evidence checks succeed. Re-fetch comments afterward when the comment tool supports it, and confirm the requested final state by comment ID.

Set the outline state:

pending — any blocking open question, feedback item awaiting a decision, requested comment action that failed, or comment content awaiting a disposition remains;
ready — every input is accounted for, the audit passes, and no blocking question or unresolved comment content remains. An incorporated comment left open because resolution was not authorized does not by itself block content readiness; report that state accurately.

This step is complete when the state is unambiguous and every failed check has either been repaired or is named as pending.

重新阅读渲染后的大纲，并检查以下所有事项：

每个请求项都有记录的处置结果；
每项目标最终状态需求至少属于一个阶段；
每个范围内的阶段贡献都可追溯至某项需求或已验证约束；
阶段顺序无环，并且每个前置条件都先于其使用方存在；
每个阶段都能在自身边界完成验证，无需依赖后续阶段的工作；
每个变更的文件、接口、迁移和测试职责都出现在正确阶段；
自动化检查使用真实的代码库命令，人工检查仅覆盖无法消除的主观判断；
实施概览与各阶段章节具有相同的数量、标题、顺序和完成状态；
未决问题、未解决的反馈和未解决的产物评论均已明确列出。

仅在相应的产物编辑和证据检查成功后，才执行已授权的评论回复或状态变更。如果评论工具支持，应在之后重新获取评论，并通过评论 ID 确认所请求的最终状态。

设置大纲状态：

pending — 存在任何阻塞性未决问题、等待决策的反馈项、执行失败的评论操作，或等待处置结果的评论内容；
ready — 所有输入均已处理、审核通过，并且不存在阻塞性未决问题或未解决的评论内容。已纳入大纲但因未获授权解决而仍保持打开状态的评论，本身不妨碍内容就绪；应准确报告该状态。

当状态明确无歧义，且每项失败的检查都已修复或被列为 pending 时，本步骤完成。

6. Select the handoff

6. 选择交接方式

Capture any artifact permalink returned while reading or editing the outline. Set

ARTIFACT_TARGET

to that permalink when available, otherwise to the local outline path. Then choose exactly one template:

For pending, read the pending-review handoff.

For ready, read

.agent-work/workspace.json

and

.agent-work/workspace.local.json

when present; the local file overrides shared values. Run

git rev-parse --git-dir

If the Git directory contains
```
.git/worktrees/
```
, read the in-worktree handoff.
Otherwise, if the effective workspace configuration sets
```
disabled: true
```
, render the configured branch template or default to the task slug. Check
```
git status --short
```
,
```
git branch --show-current
```
, and whether that branch already exists; switch to the existing branch or create it from the current HEAD only when the checkout preserves the working tree. A checkout conflict makes the result pending. After a successful checkout, read the workspace-disabled handoff.
Otherwise, read the worktree-setup handoff.

Replace every template placeholder, including

ARTIFACT_TARGET

, and respond with the selected template only. The handoff is complete when it reflects the actual readiness, workspace mode, branch, and a usable artifact location.

记录读取或编辑大纲时返回的任何产物永久链接。有永久链接时，将

ARTIFACT_TARGET

设置为该永久链接，否则设置为本地大纲路径。然后选择以下模板之一：

对于 pending，阅读待审核交接文档。
对于 ready，在文件存在时读取
```
.agent-work/workspace.json
```
和
```
.agent-work/workspace.local.json
```
；本地文件覆盖共享配置中的值。运行
```
git rev-parse --git-dir
```
。
如果 Git 目录包含
```
.git/worktrees/
```
，阅读worktree 中的交接文档。
否则，如果有效的工作区配置设置了
```
disabled: true
```
，则渲染配置的分支模板，或默认使用任务 slug。检查
```
git status --short
```
、
```
git branch --show-current
```
以及该分支是否已经存在；仅当 checkout 不会破坏工作树时，才切换到现有分支或从当前 HEAD 创建该分支。checkout 冲突会使结果变为 pending。成功 checkout 后，阅读工作区禁用交接文档。
否则，阅读worktree 设置交接文档。

替换模板中的每个占位符，包括

ARTIFACT_TARGET

，并且仅使用所选模板作出响应。当交接内容反映实际就绪状态、工作区模式、分支和可用的产物位置时，交接完成。