resume-handoff

从交接记录恢复工作

上一个会话结束时，工作尚未完成，并在项目的规划文件夹中留下了 docs/<feature>/HANDOFF.md（除非项目使用了其他位置）。你没有之前的对话记录，只有项目树、交接记录以及其中引用的文档——而这份交接记录是以你会在动手前通读全文为前提编写的。

你的表现取决于两个彼此牵制的方面。你的第一个小时必须有所产出，而不是考古——交接记录的存在就是为了让你不必重新推导其中已有的信息。你也必须恰如其分地信任交接记录——它只在某个日期时准确无误，由一个时间紧迫的 Agent 写成，此后唯一变化的只有项目树。恢复会话时若相信一份过时的交接记录，就会在已不存在的分支状态上继续工作；若忽略交接记录，就得再次踩进其中已经点明的每个陷阱。

write-handoff 技能说明了编写者被要求在交接记录中写些什么。读一遍该技能：了解这份文档应该包含什么，才能知道缺少了哪些内容。

下文中，<main> 指主集成分支（例如 main 或 dev），“问题日志”指项目记录未解决问题的位置（如果项目没有既定惯例，就查看计划旁的问题章节或文件）。

本技能的定位

• 本技能 — 接手流程。阅读、核实、提出建议并提问；用户确认后，再合并并继续使用与文档匹配的执行技能。流程到交接时结束，不负责完成整个功能。
• execute-plan — 接手流程完成且功能已有 PLAN.final.md 后使用。在这里编写代码。
• execute-roadmap — 功能已有 ROADMAP.final.md，或交接记录描述了并行执行的多个计划时使用。在这里进行说明和审查。
• write-handoff — 编写者使用的技能。在本次会话结束时你也会用到它，因为你几乎肯定也会留下一些尚未完成的工作。
• close-plan / close-roadmap — 如果核对结果表明范围内的工作其实已经完成，那么交接记录就是过时的，无需恢复工作。说明这一点并切换到相应流程；不要凭空编造下一阶段。

输入

参数会指定功能，可选地指定范围，以及可选地指定模型或工作量指令，例如：

• /resume-handoff cloud-sync
• /resume-handoff spell-check p4-p5
• /resume-handoff finish the roadmap, high effort for the workers

范围和指令会原样传递给执行技能；按其规定解析，并在 Agent 工具支持时遵循模型／工作量指令。如果参数仅为 HANDOFF.md 的路径，则功能名称就是该文件所在的文件夹。

动手前必读

按以下顺序，在执行第一个会更改目录树的命令之前，读完所有内容：

1. 项目的 Agent 入门指南（AGENTS.md、CONTRIBUTING.md 或类似文件）。每次交接都假设你已读过该文件——包括测试规则、文档索引、关于你可以在哪些地方工作的规则——通常会在开头几行明确说明这一点。
2. 完整阅读 docs/<feature>/HANDOFF.md。 不要只看开头几屏。陷阱都在底部，而你跳过的那个陷阱，正是你会踩到的那个。
3. 按交接文档指定的顺序阅读其中列为权威依据的文档——通常是最终文档，然后是决策记录或契约，再然后是 EXECUTION.md，最后是问题日志。如果文档说“摘要不是规范”，请相信它：交接文档对已构建内容的文字回顾，是整页最可能出错的部分，因为它从写下那一刻起就成了副本。
4. 项目声明的原则（PRINCIPLES.md 或类似文件，如有），以及与本次工作涉及代码相关的区域文档。

不要阅读各修订版。 PLAN.revN.md 和 ROADMAP.revN.md 记录了最终文档的形成过程；执行技能只依据最终文档开展工作。若交接文档要求你阅读某个修订版中的特定推理内容，则阅读该部分。

对照代码树核实交接内容

交接文档包含一系列说法。核实每一条的成本都很低，而判断错误的代价很高，所以行动前要逐条核实。这与 close-plan 对 EXECUTION.md 的要求相同：这些都是说法，不是事实。**本节及后面两节的所有操作均为只读。**用户确认方案之前，不得对代码树作任何更改。

你当前的位置。git rev-parse --show-toplevel 必须指向交接文档所述的检出目录，或该目录的迁移副本——不同机器上的盘符和根目录可能不同，而不属于此根目录的路径不归你修改。如果检出目录（或工作树）不存在，但分支存在，请注明创建它是你首先要提议的事项。如果本地也没有该分支，且交接文档称没有推送过，请停止：工作在另一台机器上，这里无法找回。告诉用户分支名称和机器名称。

分支状态，并与交接文档所述内容核对：

• git status——代码树是否干净？恢复工作时如果代码树不干净，说明上次会话在写入过程中停止了，或者此后有人在这里做过修改。先查看差异，再决定如何处理。
• 先执行 git fetch，然后执行 git log --oneline <branch>..<main> 和 git log --oneline <main>..<branch>——交接文档所述的超前／落后提交数只在其撰写当日成立。如果数字增加了，交接文档中的合并建议是基于更早的 <main> 写的。
• git log origin/<branch>——“尚未推送”这一说法是否仍然成立？答案会改变出错的代价。
• 交接文档引用的每个提交哈希都必须存在（git cat-file -t <hash>），最新的提交应位于分支顶部或接近顶部。**交接文档日期之后提交的任何内容，都是交接文档未知的工作。**信任“从哪里继续”之前，先阅读这些提交。

已构建的内容，并与代码核对。对于交接文档和 EXECUTION.md 声称已完成的每个阶段或计划，打开代码，检查其是否实现了最终文档验证步骤所述的功能。阶段是否完成，取决于代码是否实现了相应功能，而不是三份文档是否都声称已完成。恢复工作时无需重新运行所有测试套件——但无法确认的说法必须继续标记为待确认，而不能当作事实。

无人关注期间发生的变化：

• 问题记录——交接文档写好后，用户可能已经回答了问题；答案可能解除交接文档所称的阻塞，也可能推翻其所称已定的决定。阅读每一条记录；交接文档是在这些答案出现之前写的。有些交接文档的目的就是供“用户回答 Q5 和 Q6 后的会话”使用。
• **阻塞项。**交接文档称“等待另一个分支合并到 <main>”在撰写当日或许属实；请确认现在是否已合并。已解除的阻塞项会让工作纳入当前范围；尚未解除的仍是阻塞项，不因交接文档中的排序建议而改变。
• **既有故障。**交接文档列出父分支上失败的测试，是为了避免你追查这些问题。先确认清单仍然准确——在父分支上运行这些测试，或查看其最近的 CI 结果——再决定是追查失败还是将其排除。
• **私有记忆。**交接文档引用仓库外的记忆或笔记，但本次会话可能无法访问。代码树才是记录。如果相关信息很重要，就应写入交接文档或其他文档；在会话结束时撰写下一份交接文档时，将其补充进去。

将核实结果整理成简短表格，列出：说法、代码树实际情况、建议采取的措施。这是下文提案的第一部分。

如果没有 HANDOFF.md，你就不是在继续处理交接，而是在考据。请明确说明这一点。根据 EXECUTION.md、问题记录、git log 和最终文档重建同一张表——执行相关技能本就知道如何标记已提交的工作——并预期有些问题没有留下记录。请在本次会话结束时，写出一份你希望自己当初收到的交接文档。

调查合并情况

交接说明中的首要操作通常是先合并 <main>，再让任何操作触及工作区。现在先调查，不要执行合并——也就是merge-branch检查关卡中“合并前”的部分：

• 执行 git log --oneline <branch>..<main> 和 git diff --stat <branch>...<main>，然后查看涉及此功能所依赖文件的差异块。说明 <main> 增加了什么、哪些内容与这项工作相关，以及你预计会在哪里发生冲突。
• 点明交接说明记录的冲突处理规则，并说明你会遵照执行：“已发布的决策记录编号优先，新加入的编号顺延”；“字符串表和文档索引预计会发生追加冲突”。这些规则是上次付出代价得出的；这次用不同方式解决冲突，就是做出一个没人决定过的第二项决策。
• 建议合并方向——长期分支通常采用 <main> → 当前分支，并在当前分支上验证；说明理由。

如果交接说明中的首要操作另有其事——例如在设计方案前向提供方确认事实、删除多余的工作区副本或回答问题——那就先调查这件事，不要因为阶段列表看起来更像是在推进工作，就直接跳到阶段列表。

提出工作范围

交接说明中“下一步做什么”部分规定了顺序；用户的论据会缩小或覆盖这个顺序；协调结果则会对两者进行调整。像执行技能那样进行判断——根据最终文档的标题匹配 ID，灵活处理，并划掉已提交的内容——同时遵守交接说明新增的三条规则：

• 阻塞项仍然是阻塞项，直到协调结果表明阻塞已解除。不要只做被交接说明因某个理由而延期的阶段中“无需等待答案的部分”；那样会导致阶段被重复构建。
• **刻意未完成的内容应继续保持未完成。**交接说明列出有意留空的部分，是为了让你扩展工作，而不是去填补它们。擅自填补这些空缺，就是在用户缺席时做出产品决策。
• 降低优先级意味着需要询问。“里程碑 P——未经询问不得启动”不属于工作范围，不管你有多闲都一样。

按你会采用的构建顺序列出工作范围，并说明第一个增量是什么，以及如何验证。

先询问，然后等待

**现在停下来，把提案交给用户。**这是整个接收流程一直在准备的检查点，必须在第一条会改变工作区的命令之前进行。用完整句子说明，不要使用交接说明中的简写：

1. 交接说明中的说法与工作区实际情况——提供协调表，列出所有矛盾以及你建议如何处理。
2. 你准备执行的合并——说明将合入什么、预计在哪里发生冲突、会遵循哪些已记录的规则，以及合并方向。询问用户是否允许合并。
3. 之后将继续开展的工作——以列表列出确定后的工作范围、第一个增量，以及你会采用的执行技能。询问这些是否正确。
4. 需要用户回答的事项——任何会阻碍第一个增量的待解问题、交接说明称已完成但代码并不支持的阶段，或你无法确认是否已解除的阻塞项。

然后等待。用户可能会确认、纠正工作范围，或给出新指示——从这里开始，这三种情况各自都属于不同的会话。不要仅凭交接说明中的指示就执行合并，也不要在“等他们考虑时”开始构建：交接说明本来就是为一个会先询问的会话而写的；在无人推送的分支上擅自合并，是最昂贵的错误。如果用户在调用时说过“我睡觉时继续做”，这授权的是你在本次回答之后继续执行，而不是免去询问——仍然要先问，并说明你正在等待。

如果协调后发现没有任何待办事项，就如实说明，而不是提出工作，并指向 close-plan 或 close-roadmap。

合并，然后继续执行当前技能

用户确认后：

• 删除 HANDOFF.md。 它只为此刻而写，现在已完成使命：其中的说法已核对，其陷阱已纳入你的工作规则，其排序也已成为确认后的范围。若仍留在代码树中，它会成为下一位读者最信任的页面，而方向一旦改变，它就不再准确。将其作为一个独立的小提交删除，或随合并一起删除。如果本次会话结束时还有未完成的工作，你需要在最后重新写一份——依据本次会话的代码树，而不是上次的代码树。
• 必须经过 merge-branch 关卡进行合并，绝不能机械操作——<main> → 分支，按你所说明的规则解决冲突，并在那里验证。若某项解决方案是在两种行为而非两段文本之间作出选择，请将其记入问题日志。
• 在构建任何内容之前，先在合并后的代码树上运行一次测试套件，这样之后遇到的每个失败，要么由你造成，要么已列入预先存在的问题清单，而不是合并导致的。
• 如果合并改变了范围——某个阶段现在与 <main> 已合入的内容冲突，或者某个阻碍已解决或新出现——请在开始前简要说明。小幅调整只需报告；如果工作计划不同，则需再次征求确认。

现在切换。PLAN.final.md 按照 execute-plan 继续执行；ROADMAP.final.md 则按照 execute-roadmap 继续执行。如果交接文档包含“此路线图预期的工作方式”一节，那就是执行技能契约的重述，来自实际运行过该技能的人——请遵循它。将以下内容带入工作中：

• 将陷阱转为长期指令。 交接文档中提到的每个陷阱，都要纳入你自己的工作规则以及分配给每个子 Agent 的任务说明——被锁定的构建输出、在某个平台上会失败的清理顺序、工作目录会持续保留的 shell，以及报告完成却没有提交的 Agent。提前说明一次陷阱，就能让子 Agent 也免于为此付出代价。
• 问题日志中的决策已经确定。 不要因为你不记得理由就重新作出决定；日志记录了未被采纳的选项，这样你就能在与用户沟通后有意地重新讨论，而不是意外地反悔。
• 交接文档中那些在用户缺席时作出的决定，必须继续标明这一点。如果其中某项现在看起来不妥，就在日志中新增一个问题，而不是悄然推翻决定。
• 论证中关于模型或投入的指示，按执行技能规定的方式适用。

从现在起，由执行技能负责整个流程：每次完成一个经过验证的增量，每个增量提交一次；将问题记录下来，而不是让它们阻碍工作；直到确认的范围全部完成，或所有未受阻的工作都已完成。

收尾

执行中的技能所规定的收尾步骤仍然适用——EXECUTION.md、ACCEPTANCE.md、干净的工作树，以及通俗易懂的报告。此技能还增加了交接本身：

• 如果还有未完成事项，请重新编写一份 HANDOFF.md，并遵循 write-handoff。双方就方向达成一致时，旧文件已被删除，因此这份文件应描述本次会话的工作树：标注日期，在开篇说明本次会话的范围，只保留仍然成立的陷阱——不会再次出现的冲突所留下的陷阱，只会给下一位读者造成干扰——并补充你遇到的陷阱。将旧页面从私人记忆中借用的所有事实直接写入文档。
• 如果范围内工作已全部完成，就不要编写交接文档。 已完成工作的交接文档，只会成为关于本次工作的第四份摘要，并在内容失实时仍被人当真；EXECUTION.md 记录已完成的工作，而 close-plan 或 close-roadmap 会归档该文件夹。
• 在给用户的报告中，用一段话说明交接文档所述内容有哪些与工作树不符，以及你对每一处差异做了什么处理——这是用户无法根据上一次会话预料到的本次会话内容。然后说明构建了什么，用产品语言描述；提供 ACCEPTANCE.md 的链接；并列出等待用户决定的问题。