交接
将完成的变更打包,使其审查者永远无需从差异中反向推断意图。为手握差异的审查者撰写——除此之外没有任何规划文档、会话记录,也不假定这些文件存在。
解析任务
输入可以是任意部分引用——工单 ID、slug、规划工件的路径——或为空,表示当前会话的任务;在新会话中,根据分支名和最近提交进行推断。将其解析到任务的规划主页:项目规划目录下的 <id>-<slug>/ 子目录,或共享家庭目录中的扁平 <id>-<slug>.* 文件。找到一个明确匹配 → 继续,说明主页和找到的工件。如果推断出或有多个候选项(-vN,……)→ 首先确认。如果显式引用在本地没有匹配 → 停止并询问;切勿猜测。
收集
读取以下内容,跳过不存在的项:
- 任务工件 —— 规划主页中的每个
<id>-<slug>*.md文件:工单、需求、计划、决策日志、之前的审查和交接轮次,以及其他匹配的文件。 - 相关工单 —— 仅限一层跳转:父级(仅向上越过薄容器)、直接前驱/后继、显式关联、家庭目录兄弟;绝不展开它们自己的关联。优先使用本地
.TICKET.md文件;仅当某个关联没有本地文件且看起来对“为什么”这部分至关重要时才从工单跟踪器获取——如果不确定是否应获取,就询问。 - 会话记录 —— 当会话产生了变更时:决策、转折、约束。
- 差异对比 —— 针对目标分支的差异,以及提交标题。
每项来源只读取一次,不需要比工件更深入的阅读:整体浏览差异,只深度读取你将在审查指南中命名的文件,绝不逐个提交重建历史——哪个提交改变了什么,那是差异的事,不是你的。
然后,将计划的步骤和验收标准与差异进行双向匹配——计划中但缺失的,以及存在但未计划的。当每个来源都已读取或确认缺失,并且每个计划项都已匹配时,完成收集。
绝不编造理由
仅在来源提供了“为什么”时才陈述。对于没有任何来源解释的偏差,向作者询问一次;如果无法回答或无法询问,则以直白的文字标记后发布(“没有记录为什么——值得确认”),因为这可能是无意的遗漏而非决策。来源是你进入的门槛,而不是审查者的阅读内容:它决定你可以写什么,并且绝不出现在文本中。 不确定时,总是询问。绝不猜测。
工件
规划主页中的 <slug>.HANDOVER.md 文件;如果已存在则使用 <slug>.HANDOVER-2.md、-3 ,……——绝不覆盖。如果没有规划主页 → 展示内容并询问保存位置。其正文可直接粘贴作为 PR 描述,并能独立存在:
- 只提及审查者可以打开的内容 —— 工单跟踪器的 URL,或你确认已提交到分支上的文件。其他所有内容——规划文档、决策日志、会话记录、提交哈希——既不链接也不命名:直接写明其内容(“这本来是要……”),从不说明在哪。
- 除非某个“为什么”依赖于一个关联工单(“之所以这样构建,是为了为 做准备”),否则不提及相关工单——此时引用其跟踪器 URL。
- 控制在一屏以内,大约 400 字;下面的上限是限制,不是目标。
- 面向审查者的直白措辞,绝不使用本技能自己的词汇。在起草之前,实际调用 use-conversational-language——仅凭记忆背诵其规则不算。
章节,只有在确实为空时才跳过:
- 变更内容与原因 —— 2–3 行。
- 值得了解的决策 —— 至多 5 行,每行:选择了什么或什么偏离了计划,其理由或缺少理由的标志,以及在代码中何处查看。
- 审查指南 —— 少数几个需要仔细判断的文件及其原因;其余文件标记为机械性的。
- 已知问题 —— 至多 3 个:不足、假设、未解决的问题。
完成条件:每个章节都已填写或有意跳过,没有读起来像是已验证但实际未验证的内容,并且文本中没有指向审查者无法打开的内容。
边界
- 不修改任何源文件;只写入交接文档。
- 绝不推送或打开/评论 PR —— 发布由用户明确决定。