iterate-design-discussion

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Iterate a design discussion

迭代设计讨论

Revise the existing design discussion in place. Preserve its decision trail, ground factual changes in evidence, and leave every design question in an accurate open or resolved state.

就地修订现有设计讨论。保留其决策轨迹，以证据为依据进行事实性变更，并确保每个设计问题都准确处于待解决或已解决状态。

1. Establish the revision

1. 确定修订范围

Identify both the design-discussion artifact and the revision input. Input may be direct feedback, an approval or rejection, referenced files, or artifact comments.

If the user supplied no feedback or comments, ask:

Which part of the existing design discussion should we revise, and what outcome should the revision produce?

Then stop and wait. If the task directory or artifact cannot be identified from the request and conversation, ask for its path and wait.

This step is complete only when one existing design-discussion path and at least one actionable revision input are identified.

识别设计讨论文档（artifact）和修订输入。输入可以是直接反馈、批准或拒绝、引用文件或 artifact 评论。

如果用户未提供任何反馈或评论，则询问：

应修订现有设计讨论的哪一部分，修订应产生什么结果？

然后停止并等待。如果无法从请求和对话中确定任务目录或 artifact，则询问其路径并等待。

只有确定了现有设计讨论的路径和至少一项可执行的修订输入后，本步骤才算完成。

2. Load the complete record

2. 加载完整记录

Use

ls -La .agent-work/tasks/TASKNAME

to inventory the task directory; it may be a symlink. Open the listed paths directly because search and glob operations may not traverse that symlink. Read every file in the directory in full, including the current design discussion, ticket or task, research, and any later artifacts. Fully inspect every additional file or directory the user names.

Use this precedence when sources disagree:

design discussion > research > ticket or task

The design discussion contains decisions made after the earlier artifacts. Treat later artifacts as evidence of subsequent work, not as silent authority to rewrite a design decision. Surface any conflict that the user's feedback does not resolve.

This step is complete only when every task artifact and mentioned source has been read, the discussion's original path is known, and every contradiction relevant to the revision has been recorded.

使用

ls -La .agent-work/tasks/TASKNAME

盘点任务目录；它可能是符号链接。应直接打开列出的路径，因为搜索和 glob 操作可能不会遍历该符号链接。完整读取目录中的每个文件，包括当前设计讨论、工单（ticket）或任务、研究资料以及所有后续 artifact。完整检查用户提及的每个其他文件或目录。

当来源之间存在冲突时，遵循以下优先级：

设计讨论 > 研究 > 工单（ticket）或任务

设计讨论中包含在较早 artifact 之后作出的决策。应将后续 artifact 视为后续工作的证据，而不是可以擅自改写设计决策的权威。如果用户反馈无法解决来源之间的冲突，应明确指出。

只有读取了所有任务 artifact 和提及的来源、知道了讨论的原始路径，并记录了所有与修订相关的矛盾后，本步骤才算完成。

3. Build a revision ledger

3. 建立修订台账

Create an internal ledger with one row per instruction, decision, factual claim, and comment thread. For each row record its target, required evidence, and one disposition: apply, reject with reason, ask a focused question, or leave open pending evidence.

Distinguish design authority from factual authority:

A clear user choice, approval, or rejection decides a design question.
A claim about current behavior, integration, or code conventions requires verification before it changes the artifact.
Ambiguous feedback that would materially change the architecture requires a focused clarification. Continue with independent, unblocked rows.

For artifact comments:

When comment bodies are supplied, treat each thread as a separate ledger row and give later replies in that thread their chronological meaning.
When comments are referenced but absent, fetch them with an available artifact-comment reader. If comment capabilities are unavailable, ask the user to supply the comments or reopen the work where the artifact is accessible.
When the user has not selected a comment action, ask whether they want the document updated only, updated and satisfied comments resolved, or findings posted as replies. Comment replies, resolution, and deletion require the user's explicit choice.

This step is complete only when every input and comment thread has exactly one disposition and any external comment mutation has explicit authorization.

创建一个内部台账，每条指令、决策、事实性陈述和评论线程各占一行。对于每一行，记录其目标、所需证据，以及以下四种处置方式之一：应用、附理由拒绝、提出聚焦问题，或保持待定以等待证据。

区分设计裁定权与事实依据：

明确的用户选择、批准或拒绝可裁定设计问题。
关于当前行为、集成方式或代码约定的陈述，在改变 artifact 之前需要验证。
如果反馈含糊且会实质性改变架构，则需提出聚焦的澄清问题。同时继续处理其他独立且不受阻塞的记录。

对于 artifact 评论：

提供评论正文时，将每个评论线程视为独立的台账记录，并按时间顺序理解线程中的后续回复。
引用了评论但未提供正文时，使用可用的 artifact 评论读取器获取。如果评论能力不可用，则请用户提供评论，或在可以访问该 artifact 的位置重新打开此项工作。
如果用户尚未选择评论操作方式，则询问其希望仅更新文档、更新文档并解决已满足的评论，还是将发现作为回复发布。对评论的回复、解决和删除都需要用户明确选择。

只有每项输入和评论线程都恰好有一种处置方式，并且对外部评论的变更操作均获得明确授权后，本步骤才算完成。

4. Verify changed facts

4. 验证发生变化的事实

Investigate every ledger row whose correctness depends on the repository. Start with the user's cited locations. Trace relevant implementation, integration points, callers, tests, and established analogues far enough to support or disprove the proposed edit.

For independent unknowns, delegate focused research in parallel when those helpers are available:

```
codebase-locator
```
finds owning files and related components.
```
codebase-analyzer
```
explains behavior and integration details.
```
codebase-pattern-finder
```
finds conventions, comparable implementations, and tests worth following.

Give each helper one bounded question and require file-and-line evidence. Treat its report as a map: inspect the cited primary code before placing a claim or snippet in the artifact. When the input asks how existing functionality works or requests deeper implementation detail, begin with one or more focused helpers before main-context verification. Straightforward wording edits and explicit design choices need no delegated research when the loaded record is enough.

This step is complete only when every factual row has primary evidence, every code pointer has been checked, and remaining uncertainty is represented as an open question rather than stated as fact.

调查台账中所有正确性取决于代码库的记录。从用户引用的位置开始。追踪相关实现、集成点、调用方、测试和已有类似实现，直到能够充分支持或否定拟议的编辑。

对于彼此独立的未知项，在相关 helper 可用时并行委派聚焦研究：

```
codebase-locator
```
查找所属文件和相关组件。
```
codebase-analyzer
```
解释行为和集成细节。
```
codebase-pattern-finder
```
查找值得遵循的约定、类似实现和测试。

给每个 helper 指定一个有界问题，并要求提供文件和行号证据。将其报告视为一张地图：在将声明或代码片段写入 artifact 之前，检查其中引用的原始代码。如果输入询问现有功能如何工作，或要求更深入的实现细节，应先启动一个或多个聚焦 helper，再在主上下文中进行核验。对于简单的措辞编辑和明确的设计选择，如果已加载的记录已足够，则无需委派研究。

只有每个事实性记录都有一手证据、每个代码引用均已核验，并且剩余的不确定性均表示为待解决问题而非既定事实时，本步骤才算完成。

5. Reconcile the discussion

5. 协调设计讨论

When at least one ledger row applies, edit the design discussion at its original path. When none applies, leave the file unchanged and carry each reason into the handoff. In either case, reconcile the document's internal consistency:

Update the current state, desired end state, non-goals, and proposed architecture wherever the revision changes them. Use before/after diagrams, concise pseudocode, or examples when they remove architectural ambiguity.
For each major design choice, keep viable options comparable with concrete tradeoffs and a recommendation grounded in evidence and repository conventions.
A clear user decision moves its question from
```
Design Questions
```
to
```
Resolved Design Questions
```
. Record the chosen option, rationale, and the material alternatives rejected with reasons.
An unanswered or newly exposed tradeoff remains under
```
Design Questions
```
, even when one option is recommended. Only user feedback resolves it.
A changed decision replaces the operative answer while preserving enough of the prior decision and new rationale to explain the reversal.
Refresh
```
Patterns to follow
```
with verified paths and concise multiline code examples. Remove patterns disproved by the new evidence.

When the document itself contains Markdown examples with fenced code, use a four-backtick outer fence so nested three-backtick fences remain valid.

This step is complete only when every ledger row is reflected, explicitly rejected, or visibly blocked; every major choice has a rationale; all question states match the user's decisions; and all sections agree on one architecture.

当至少一条台账记录应被应用时，在其原始路径编辑设计讨论。如果没有任何记录应被应用，则保持文件不变，并在交接结果中说明每项原因。无论哪种情况，都要协调文档的内部一致性：

当修订改变当前状态、期望的最终状态、非目标和拟议架构时，更新相应内容。使用前后对比图、简洁的伪代码或示例来消除架构歧义。
对于每项主要设计选择，使各可行选项具有可比性，列出具体权衡，并给出以证据和代码库约定为基础的推荐方案。
明确的用户决策会将问题从
```
Design Questions
```
移至
```
Resolved Design Questions
```
。记录选定的方案、理由，以及被实质性排除的其他备选方案及其原因。
未得到回答或新发现的权衡仍应保留在
```
Design Questions
```
中，即使已有推荐方案。只有用户反馈才能解决这些问题。
发生变更的决策应替换当前生效的答案，同时保留足够的信息，包括此前的决策和新的理由，以解释为何改变决定。
使用已验证的路径和简洁的多行代码示例刷新
```
Patterns to follow
```
。删除已被新证据否定的模式。

当文档本身包含使用围栏代码块的 Markdown 示例时，应使用四个反引号作为外层围栏，以确保嵌套的三个反引号围栏仍然有效。

只有每条台账记录都得到反映、被明确拒绝或被清楚标记为受阻，每项主要选择都有理由，所有问题状态都与用户决策一致，并且所有章节都围绕同一套架构保持一致时，本步骤才算完成。

6. Validate the saved artifact

6. 验证已保存的 artifact

Re-read the saved file in full and check all of the following:

It remains at the original path and retains valid artifact metadata.
Every requested change and relevant source conflict has a disposition.
Current state, desired state, non-goals, architecture, decisions, and patterns agree with one another.
Each open question asks for a real user decision; each resolved question has an explicit user answer and rationale.
Referenced paths exist, quoted code matches the repository, diagrams and fences render, and no unverified claim is presented as settled.

If comment mutation was authorized, perform it only after the artifact passes these checks. Use the available reply capability for requested findings and the comment-state capability for the authorized state change. Resolve only threads whose requested change is satisfied, and reconcile every requested operation by comment ID. Capture an artifact permalink when the read or edit operation returns one.

This step is complete only when every check passes, every authorized comment operation is accounted for, and the final path and any returned permalink are known.

完整重新读取已保存的文件，并检查以下所有事项：

文件仍位于原始路径，并保留有效的 artifact 元数据。
每项请求的变更和相关来源冲突都有相应处置。
当前状态、期望状态、非目标、架构、决策和模式彼此一致。
每个待解决问题都要求用户提供真实决策；每个已解决问题都有明确的用户答案和理由。
引用的路径存在，引用的代码与代码库一致，图表和围栏可以正常渲染，且没有将未经验证的声明表述为既定事实。

如果已授权变更评论，则仅在 artifact 通过上述检查后执行。使用可用的回复能力处理所请求的发现，并使用评论状态能力执行已授权的状态变更。仅解决其请求变更已得到满足的评论线程，并按评论 ID 核对每项已请求的操作。如果读取或编辑操作返回 artifact 永久链接，则将其记录下来。

只有所有检查均通过、每项已授权的评论操作都已完成核对，并且已知最终路径及返回的任何永久链接后，本步骤才算完成。

7. Hand off the result

7. 交接结果

Select exactly one final-answer branch after validation:

If any design question or evidence gap remains open, or any feedback/comment was not applied, read the unresolved handoff and follow it.
If the document has no open design questions, every resolved question records an explicit user decision, and no feedback or evidence gap remains, read the resolved handoff and follow it.

This step is complete only when the handoff links the artifact using a returned permalink when available and always gives its local path, reports every remaining open or unapplied item in the unresolved branch, and gives the structure-outline skill only in the resolved branch.

验证后，恰好选择以下一个最终答案分支：

如果仍存在任何待解决的设计问题或证据缺口，或者任何反馈或评论尚未应用，请读取未解决交接文档并遵循其中的说明。
如果文档不存在待解决的设计问题、每个已解决问题都记录了明确的用户决策，并且不存在尚未应用的反馈或证据缺口，请读取已解决交接文档并遵循其中的说明。

只有交接文档在可用时使用返回的永久链接链接到 artifact、始终提供本地路径、在未解决分支中报告所有剩余的待处理或未应用项，并且仅在已解决分支中给出

structure-outline

skill 后，本步骤才算完成。