close-roadmap

关闭路线图

你正在为用户完成一项功能的收尾。执行已经结束： ROADMAP.final.md 或 PLAN.final.md 已获批准并完成构建， docs/<feature>/（项目的规划文件夹，除非项目另有安排）现在存放着 规划文档、评审记录和执行产物，这些内容促成了该功能的交付。如果放任不管， 这个文件夹就会成为下一个 Agent 首先阅读且最信赖的内容，而其中大部分已不再属实。 你的工作是只留下已存在的内容（权威、当前，且从项目的 Agent 指引出发只需一步即可到达）和尚待完成的内容（下一份路线图的 rev1）， 不留其他内容。

评判标准是：一个全新的 Agent 仅阅读目录树，能否以最少的跳转了解该功能的真实情况； 以及最终文档中曾承诺的每一项内容是否仍然可查：已交付、转入后续计划、延期， 或由用户决定删除。

绝不要擅自放弃工作。 最终文档承诺的计划就是产品承诺。如果没有交付， 就必须转入下一份路线图，除非用户另有决定；如果用户另有决定， 就将其记录到项目的延期工作记录中（如果没有此类记录，就在文件夹的 README 中新增 “Deferred”部分），并注明原因，避免日后被悄悄重新决定。

记录决定时绝不要擅自作出决定。 记录已作出的决定是你的职责；作出新决定则不是。 如果记录含糊不清——例如执行偏差没有说明原因，或日志中记录的问题用户从未回答—— 就用简单明了的语言提问，每个问题只问一项决定。

输入

功能名称来自参数（例如 /close-roadmap notifications）。 阅读 docs/<feature>/ 中的所有内容，然后按以下顺序阅读：

1. 最终文档——ROADMAP.final.md 或 PLAN.final.md（如果该功能有 TECHNICAL.final.md 或 EXPERIENCE.final.md，也要阅读）。 如果只有 rev 版本，就停止：没有内容获批，因此无需收尾。
2. 执行记录——EXECUTION.md（已交付的内容及其提交哈希）、问题日志（偏差和未回答的问题，具体位置由项目决定）、ACCEPTANCE.md（要求人工核验的内容）、HANDOFF.md（提供给下一个 Agent 的简报），以及任何未测试事项清单或测试计划。这些都是陈述，不是事实；下一步要核实这些内容，而 ACCEPTANCE.md 也必须在分类处理前单独评审。
3. 代码和历史记录。 查看分支的 git log 和 EXECUTION.md 引用的提交；然后检查最终文档标记为已完成的每项计划对应的代码。只有代码实现了计划中所述的验证步骤，该计划才算已交付，而不是文档说它已完成就算。 如果已交付计划的实现方式与计划不同，这属于决定（见“已交付工作”），而不是需要掩盖的差异。
4. 该功能涉及的权威文档——根据项目的文档索引（例如 AGENTS.md 或 CONTRIBUTING.md 中说明各类文档位置的表格），查找架构、数据模型、运维、用户指南和产品状态的文档；如果文档索引中有该功能自己的条目，也要查看。写入之前先阅读这些文档，让新增内容放在相邻内容旁边，而不是另起一份重复文档。
5. 项目中任何已完成收尾的功能文件夹，以确保结果结构一致。

按照同类技能的做法，对照主集成分支检查（执行 git fetch，然后运行 git log --oneline <branch>..<main>，其中 <main> 例如为 main 或 dev）。如果树在此期间已发生变化，此时再收尾路线图就会记录一个不复存在的状态；请说明情况，并在合并前先询问（参见 merge-branch）。

验收审查——分诊前先确认这一项

ACCEPTANCE.md 是要求人工逐项检查的清单（参见 write-acceptance）。之所以有这份清单，是因为其中的检查无法由机器执行，因此这是记录中唯一无法通过阅读代码来确认的部分。逐项检查，并为每项给出结果：

结果	含义	你要做什么
通过	用户或测试人员报告了指定的可观察结果	将其作为该计划已落地的证据
失败	他们报告了其他结果	该计划尚未落地——它处于待处理状态，V2 rev1 会说明观察到的情况
从未运行	从未收到任何结果反馈	询问；得到答复前，该计划不算落地

从未运行的检查属于未经验证的工作，而非已落地的工作——这与从未执行验证步骤的计划状态相同。不要因为代码看起来正确就悄悄将其提升为已落地：它之所以列在清单中，正是因为阅读代码无法得出结论。针对每项检查分别向用户提一个问题，询问现在是否运行，或是否接受这项工作未经验证；如果用户接受未经验证，则在项目记录当前可用功能的所有位置将其标记为部分完成，并在 V2 rev1 中将验证列为一项计划。

将结果作为证据列填入下方的台账，并在报告中说明哪些计划是基于人员确认而非测试套件通过而落地的。如果某项检查在此功能关闭后仍值得执行——它属于回归检查，而非一次性验收——则在删除 ACCEPTANCE.md 前，将其移至该功能当前的测试计划中。

分诊——修改文件前先复述确认

最终文档中的每个里程碑和计划，以及问题日志、任何未经测试的清单和测试计划中的每一项，都必须且只能归入以下四种状态之一：

状态	含义	归档位置
已落地	已在代码中验证，并有对应提交——若有验收检查，该检查也已通过	规范文档；删除计划文本
待处理	已承诺但尚未构建，或仅部分构建	ROADMAP-V2.rev1.md，并在括号中保留原始 id
已延期	用户决定暂不构建	延期工作记录——记录内容、原因，以及什么情况会改变决定
已放弃	用户决定不再构建	在 V2 rev1 的“Not carried forward”部分添加一行，并说明原因

只有用户可以指定已延期或已放弃。将台账以表格形式列出——id、标题、状态、证据（提交哈希或文件）——并标出需要答复的问题，然后等待用户同意后再删除任何内容。 台账是这项技能中唯一无法事后从项目树中还原的产物，因此也要将其写入提交消息。

尚待完成的事项 — docs/<feature>/ROADMAP-V2.rev1.md

这是 rev1，因为它会重新进入 draft-roadmap 审查周期：rev2、rev3、 ROADMAP-V2.final.md，然后是 execute-roadmap。 按 draft-roadmap 的方式撰写，并遵循该技能对每份计划的常设要求。

• 以“从这里继续”开篇：用一段话说明上一份路线图交付了什么（指向 README，而非复述 README），以及还剩下什么；按紧迫程度排序，并说明排序理由。债务（即对用户作出的承诺尚未兑现）优先于功能。
• 延续不变量。 最终文档中的执行约定、常设要求和不变量继续有效；新计划要依据这些内容审查。请复制它们，不要链接到即将删除的文件。
• 每项待处理计划都保留其输入、输出和验证步骤，并根据当前代码重写——如果计划所指的接缝已移动，就必须指出新的接缝。部分完成的计划要说明现有内容和剩余工作，并注明已完成部分所在的文件。
• 日志中的未决问题，如果用户尚未回答，就成为 rev1 的待解决产品问题；每项都要列出日志中记录的选项和建议。已回答的问题属于决策，应写入决策记录，而非此处。
• **“不再延续”**列出用户放弃的事项及原因，让审查者知道路线图是有意缩减的。

不要重述已完成的内容。rev1 以 README 为依据。

已落地的工作——写到读者会去看的地方

根据项目的文档地图，为每项已落地工作安排文档归属。功能文件夹只包含专属于该功能的内容；其他领域的读者需要的信息应写入共享页面。

• 决策 → 决策记录（ADR），每项决策各一份，前提是项目使用 ADR。 问题日志和 EXECUTION.md 中记录的执行偏差，是在压力下作出的决策，通常从未留下记录；趁理由还在代码库中，现在就补上，并说明未采纳的替代方案。检查最终文档在审查期间解决的决策（“对 revN 意见的回复”），确认代码现在是否已体现这些决策。从项目的编号登记表中取号；如果其他分支已发布某个编号，以已发布编号为准——新文档须重新编号，并同步更新交叉引用。如果项目已有共享登记表，不要创建按功能划分的决策文件。
• 模型 → 项目的数据模型文档，并链接到决策记录。如果某个功能有自己的模型（例如 schema 或线格式），且共享页面不应包含这些内容，则在该功能文件夹中单独创建数据模型页面。
• 代码结构和数据流 → 跨模块时写入共享架构文档；若涉及功能自身的内部结构，则写入文件夹中的 ARCHITECTURE.md。每个文件都要说明规范依据是什么——通常是代码中的类型——并注明当文档与代码不一致时，以代码为准，文档内容有误。
• 运维、API、事件、配置和环境变量——写入项目相应的文档。如果其中任何文档由工具生成，就运行生成器并提交生成结果，不要手动编辑。
• 用户要做什么 → 用户指南。当前可用功能 → 项目的产品状态页面，如实说明已完成和部分完成的内容：如果计划落地后仍有未测试项，在有人验证前就应标记为部分完成；验证工作应列入 V2 rev1 计划。
• 暂未处理的代码 → 项目的技术债务记录，说明具体内容、暂缓原因，以及满足什么条件后可以安全处理。执行者在 EXECUTION.md 中写下的“我没有处理 X，因为……”通常就属于这类内容。
• 如果手动测试计划仍是该功能的手动测试方案，就保留它，并更新已知缺口。

不要编写重复共享页面内容的摘要文档。README 负责指路；共享页面负责承载内容。

文件夹中的 README.md

编写或重写 docs/<feature>/README.md：

1. 用一句话说明该功能是什么，这是后续所有内容的依据，然后添加导航表：想了解…… → 阅读……，将所有共用内容指向共享页面，其余内容指向文件夹自身的文件。路线图作为下一行，且只占一行。
2. 说明此文件夹包含哪些内容，每个文件占一行，并说明各自的用途——包括哪些是历史资料，哪些是规范性内容。
3. 说明新工作应放在哪里，用一张表防止文件夹再次杂乱：决策写入决策记录，模型变更写入数据模型页面，延期工作写入路线图，等等。
4. 尽可能简短地概述现有内容，供不会点进去查看的读者阅读。不要再写一份架构文档。

将 notes/ 标记为历史资料，并为其编写独立的 README：说明每份笔记原本是什么、后来被什么取代、哪些方面说对了、哪些方面不对。保留这些笔记——它们记录了路线图最初的思考依据，但其中没有任何内容具有规范效力，也不能据此实施。

删除目录结构不再需要的内容

用户批准清单并完成规范文档编写后：

• 删除最终文档、所有 .revN.md 和 .revN.notes.md、EXECUTION.md、该功能的问题日志、ACCEPTANCE.md、HANDOFF.md 以及任何未测试列表——先将仍值得重跑的验收检查纳入该功能当前的测试计划，因为无人会再运行的检查已经失去作用，但回归检查仍有价值。每轮结束时，这些文件都已提交，因此 git 保留了迭代历史；文件留在目录树中，只会让 Agent 误以为它们仍是当前版本。不要将它们移到 archive/ 文件夹——那只是路径更长的删除，文件夹随后也会变得杂乱。提交说明中应列出每个删除的文件及其内容去向。
• 保留 README、V2 rev1、notes/、当前测试计划、计划仍引用的设计和资源，以及任何引用所依赖的文件——先运行 grep，因为源代码有时会按名称引用文档。
• 修复所有指向这些内容的链接。 对每个删除或重命名的路径，在文档、Agent 指引文件、README 和源代码目录中运行 grep。任何文档索引中的该功能入口都应指向 docs/<feature>/README.md，而不是路线图。
• 运行所有用于检查生成文档的测试，以及最终文档中列出的常规检查。如果没有链接检查工具，上述 grep 就是链接检查；务必在最后一次重命名之后再执行，而不是之前。

收尾

• 按照 commit-changes 将收尾内容作为一次变更提交：包括清单、各项内容写入的位置、删除的内容及其去向。除非有人要求，否则绝不推送。V2 rev1 属于同一提交；其审阅轮次应单独提交，具体按 draft-roadmap 中的说明执行。
• 使用产品语言向用户汇报：说明该功能当前的作用、仍待完成的事项及其顺序、收尾过程中用户作出的决定，以及审阅者应优先检查 V2 rev1 的哪些内容。