finalize-doc

定稿计划或路线图

本轮迭代已结束。某个修订版经过评审、答复、再次评审，最终由用户签字确认；docs/<feature>/（项目的规划文件夹，除非项目另有安排）中保存着每个修订版、每个 .notes.md，而用户回答的问题和做出选择的原因则只存在于对话中。照此保留，这个文件夹就会堆满已被取代的文档，读者不得不逐一比较才能了解最终决定；而一半的决策依据则留在无法重新打开的聊天记录里。

你要编写一份 <STEM>.final.md 文档，让新接手的 Agent 或用户可以单独阅读：先呈现经批准且完全按确认内容定稿的计划，再附上促成该计划的背景——问了什么、回答了什么、各修订版之间有哪些变化及原因、尝试过什么又撤回了什么。然后删除各修订版和备注文件，因为最终文档现在已包含它们承载的所有内容。

评判标准有两项：一是获批内容在写入最终文档时没有任何改动；二是六个月后，读者无需翻查 Git 历史，就能从最终文档中回答“为什么要这样做？”

记录决定时，绝不做决定。 如果还有问题尚未解决，文档就还不能定稿——请停下来说明是哪项问题。定稿是附带历史记录的复制工作，不是最后一次改进计划的机会。

未经签字确认，绝不定稿。 “评审者没有发现问题”不等于用户签字确认。如果对话或论证中没有签字确认，请用一句话征求确认并等待。

输入

参数中要指定功能名称（/finalize-doc webview）；如果文件夹中有多个文档主名，也可以指定主名（/finalize-doc webview TECHNICAL）。

1. 查找文档。 在 docs/<feature>/ 中，编号最高的 <STEM>.revN.md 就是已签字确认的修订版，除非用户指定了其他版本。收集所有更早的 <STEM>.revK.md 和 <STEM>.revK.notes.md。同时收集以各自主名并行迭代的配套文档（例如平台计划、实现文档）——每份都应在同一轮中各自定稿，或者用一句话明确说明为何将其排除。
2. 按从旧到新的顺序阅读每个修订版和备注文件。 “对 revN 备注的答复”部分和评审者的决定表构成历史主线；备注中的问题是待解事项，下一修订版中的答复则是相应解答。
3. 阅读对话。 用户的答复往往是在聊天中给出的，而不是写入文件——例如，针对某个修订版问题的编号答复、轮次中途重新确定范围，或一句“是的，可以”。这些都属于决定，应连同日期写入最终文档。如果你是刚开启的新会话，没有对话记录，请说明这一点：你能撰写的历史仅限于文件中记载的内容；用户应确认是否有任何决定只在聊天中做出。
4. 如果存在，请阅读 docs/<feature>/notes/*——其中记录了整个迭代所服务的产品意图。最终文档开篇应指向这里。
5. 确认没有遗留问题：已签字确认的修订版中每个“未决问题”部分都必须为空或已有答复；最后一份备注中的每条评审意见都必须已解决、说明原因后撤回，或由用户明确移交到执行阶段。其他任何情况都会阻止定稿。

最终文档——<STEM>.final.md

分为两部分，顺序如下。先写获批计划，因为它将被执行，也是 execute-plan / execute-roadmap 会读取的内容；再写历史，因为它解释了计划，也能在有人询问原因时供其查阅。

第 1 部分——已批准的计划

实质内容与签署通过的修订版完全一致，只有以下改动：

• 标题改为 <Feature> — <STEM>.final，开篇段落注明签署通过情况：由谁、通过了哪个修订版、日期，以及哪些审阅意见结束了上一轮。
• 本部分移除“对 revN 意见的回复”章节——这些章节应移到第 2 部分。
• 如果“未决问题”为空，就将其移除；如果用户在签署通过时回答了最后几个问题，则将其改为“签署通过时作出的决定”，并将每个答案记录为一条决策行。
• 对较早修订版的引用（as rev6 §4、unchanged from rev5）必须消解：最终版不得指向即将删除的文档。应内嵌所引用的文本，或改写，使最终版可独立阅读。这是最终版比修订版更长的唯一部分，而且值得这样做。
• 状态列应标为 decided，并注明日期；不得出现 proposed。

其他内容一概不动。你想润色的句子、想调整顺序的阶段、认为缺少的测试——都留给下一个修订版，不要放进最终版。如果发现某项内容确实无法成立（代码与某项声明矛盾、链接失效等），应停下来告知用户，而不是悄悄修正。

第 2 部分——我们是如何走到这一步的

整理后的对话记录。面向会问“为什么不选那个显而易见的方案？”的读者，按以下顺序撰写：

1. 起点。 用两三句话说明笔记的意图，以及 rev1 对此提出了什么方案。如果 rev1 对代码树的理解有误，也要说明——例如“这已经存在”或“这个账户并不存在”之类的发现，因为这些更正解释了后续所有内容的形态。
2. 决策，汇总为一张表。 按提问顺序，列出用户在所有修订版和审阅中被问到的每个问题：用一行写清问题、提问者（作者或审阅者，以及对应的修订版／意见）、用户的回答、日期，以及该问题最终对应第 1 部分的哪条决策行。重新确定范围的情况——即用户在迭代过程中更改产品方向——也要作为表格行列出，并注明因此哪些问题不再相关。
3. 各轮审阅。 每轮审阅用一段简短文字说明：审阅者发现了什么（按发现 ID 列出）、下一个修订版如何处理，以及哪些内容延续到了下一轮。注明用户否决的发现。如果某项发现历经三轮审阅，后来又因重新确定范围而变得无关，这正是值得保留的历史——说明它付出了什么代价，以及为何后来不再重要。
4. 尝试后又撤回的内容。 说明那些经过设计但后来移除的机制——例如无法保持一致的缓存、因重新确定范围而不再需要的方案——并说明原因。本节旨在避免下一个 Agent 再次提出这些方案。
5. 明确留待以后处理的内容（如果计划有延期部分）：指出该部分，而不是重复其内容；并补充对话中延期处理、但计划中未记录的事项。

保持客观简洁：决策写成一行，每轮审阅写成一段。若决策依据是用户原话，请直接引用（例如“先窗口，再标签页”、“好，不做了”），因为转述可能偏离原意，而原话不会。

配套文档

如果计划有配套文档并经过多轮迭代（例如主计划旁边的特定平台计划，或路线图旁边的实现文档），则应为其创建配套最终版：<STEM2>.final.md，包含相同的两部分；其中第 2 部分应保持简短，并指向主最终版中关于共同历史的记录。主最终版的第 1 部分应链接到配套最终版，而不是配套修订版。

删除 rev 和 notes

两份最终稿都写好，并根据已签字确认的 rev 重新审阅后：

1. git rm 删除所有 <STEM>.revN.md 和 <STEM>.revN.notes.md，以及配套文件的 rev 和 notes。这些 rev 保存在 Git 历史中，位于关闭各轮审阅的提交里；工作树中只保留最终稿。
2. 修复所有指向这些文件的链接：在文档、Agent 说明文件和技能中搜索每个已删除文件的 stem（例如 grep -rn "<STEM>.rev" .）。原先指向某个 rev 的 README 或 HANDOFF，现在应指向最终稿。
3. 绝不要删除 notes/。 产品 notes 记录的是意图，不是迭代产物。
4. 不要修改 EXECUTION.md、ACCEPTANCE.md、HANDOFF.md 或问题日志——这些属于执行流程，以及 close-plan / close-roadmap 的职责。

提交

只提交一次：添加最终稿、删除 rev 和 notes、修复链接。 按照 commit-changes 的要求编写提交消息；注明哪个 rev 已获谁签字确认，以及历史记录位于最终稿的 Part 2 中。除非有人要求，否则不要推送。

收尾

告知用户：写好了哪些最终稿、合并了多少个 rev 和 notes、哪些只在对话中作出的决定现已记录在案，以及哪些内容未能定稿（尚未解决的问题、未纳入的配套文件）及其原因。然后移交执行：执行计划或路线图的人员阅读最终稿；审阅者的最后检查（review-doc 中的“when the final appears”）现在可以据此进行。