orca-handover

技能：orca-handover

内容

用途与背景

• **用途：**生成一个独立完整的 .md 交接文件，让没有上下文的下一次会话打开后就能继续工作：未完成事项、有理由的顺序、作为证据的测量数据、陷阱、未解决的欠项。
• 触发条件（何时使用）：
  • 长会话即将结束，但工作尚未完成，且下一次会话没有任何上下文。
  • 刚调查出一系列发现，需要在忘记理由之前敲定解决顺序。
  • 将工作交给其他人／Agent，但工作仍然模糊不清（尚无已批准的 SPEC）。
• 非目标（何时不使用）：
  • 任务已批准且步骤明确 → 使用 plan（提供给无头 Agent 的执行简报）。
  • 只需要机器检索“上一会话做了什么” → 使用 record-episode（mem-rank）。
  • 将 worktree／终端的所有权移交给其他 Agent → 使用 orca-cli（完整交接）。

思维模型

实际运行证据（git log/status、medic）→ 剩余工作 → 阻塞关系 → sources/handover/ 中的 7 部分文件 → 索引 + 日志。

原则——为什么这个文件不同于摘要

读者什么都没有：没有 transcript，也不知道昨天试过什么、又为何放弃。摘要讲述做了什么；交接必须回答接下来做什么，以及为什么按这个顺序做。

决定这个文件是否可用的三件事：

1. 每项声明都必须有数字。“Grep 不够好”是观点。“在 8 个变更文件上：grep 怀疑 36 个，graph 25 个，重复 21 个 ⇒ 多出 15 个、漏掉 4 个”是证据——下一会话可以复查，也不必相信任何人的话。
2. **顺序必须有理由，并且必须明确指出什么阻塞什么。**平铺的列表会让下一会话先挑最简单的工作，然后撞上尚未完成的事项。
3. **陷阱是最昂贵的部分。**每个付出过代价却没有记录的错误，都会让下一会话再付一次代价。

输入与输出约定

	字段	必填？	含义
输入	会话状态（repo、未完成工作、发现）	是	通过实际运行的命令获取，不凭记忆
输入	背景概念／ADR	否	放在“预先阅读”部分中作为链接，而不是复制内容
输出	llmwiki/wiki/sources/handover/DDMMYY-<tên>.md	是	七个部分，顺序正确（见 W03 中的表格）
输出	llmwiki/wiki/index.md 中的一行 + 追加到 llmwiki/wiki/log.md	是	登记；如果 repo 有 validator，则 index_sync 显示为绿色

规则与能力

• RULE-01 (MUST)：**数字胜过形容词。**任何关于程度的说法（“慢”“很多”“严重损坏”）都必须附带数字，否则删除。
• RULE-02 (MUST)：绝对路径或精确的 repo 相对路径——下一会话可以直接复制粘贴运行，无需猜测目录。
• RULE-03 (MUST)：不要重复架构——链接到已有概念。因复制背景内容而膨胀的交接文件，没人会读完。
• RULE-04 (MUST)：记录所有尚未验证的内容——“尚未测量”“尚未交叉验证”是宝贵的信息；隐瞒它会让下一会话建立在错误的假设之上。
• RULE-05 (MUST)：不得缺少“已尝试并放弃”部分——这是最容易忘记、缺失时代价最高的部分。
• RULE-06 (MUST)：**不要复制 transcript。**交接是提炼，不是日志。超过 200 行，就说明你是在复制，而不是提炼。
• RULE-07 (MUST)：反模式：写“继续未完成的工作”，却不说明工作停在哪里、哪个文件、哪一行。
• 能力：读取 repo 状态 + 运行本地健康检查 gate（只读）；在 wiki 中写入一个文件 + 更新 index + log。

失败边界

• 无法通过命令复现的数字 → 不要编造：明确写为尚未验证（允许部分完成）。
• 工作其实已经明确且已批准 → 澄清／转为 plan；如果只需机器检索 → 使用 record-episode。
• 文件不独立完整（必须追问、路径错误、“如上所述”）→ 按 W05 自检为失败，修改后重新检查。
• 超过 200 行 → 说明正在复制 transcript，应当删减。

操作

主要工作流

步骤	类型	输入	操作	输出/退出	失败/后续
W01	确定性	repo	写作前先收集证据（git log、git status，如有 medic 也运行）	实际测量值	无法复现 → 记录“尚未验证”
W02	判断	剩余工作	找出阻塞项（先做 B 再做 A 会出什么问题？）	步骤 0 + 有理由的顺序	不存在依赖关系 → 记录“顺序不限”
W03	效果	W01–W02	编写 llmwiki/wiki/sources/handover/DDMMYY-<tên>.md，包含七个部分	handover 文件	—
W04	判断	每项工作	使用具体单位估算时间	每项工作 ⏱	—
W05	判断	文件	检查文件是否可独立阅读（路径准确、说明数字的测量对象，不写“如上所述”）	文件合格	有缺漏 → 修改并重复 W05
W06	效果	文件	登记到索引 + 日志；如有 validator，则运行 index_sync	索引/日志一致	validator 报错 → 修复

W01–W06 每一步的详细说明（权威依据）：

1. 写作前先收集证据（不要凭记忆写）

git log --oneline -15
git status --short
python3 fdk/tools/medic.py --ci 2>&1 | tail -5     # nếu repo có medic

文件中的所有数字都必须来自本次会话中实际运行的命令，不要重新估算。无法复现的数字要明确记录为尚未验证，不要四舍五入后当作事实。

2. 找出阻塞项

对于每项剩余工作，问：先做 B 再做 A 会出什么问题？ 有具体答案 → A 是步骤 0，并注明跳过后果。没有 → 顺序不限，明确说明顺序不限。

3. 编写文件 llmwiki/wiki/sources/handover/DDMMYY-<tên>.md

使用独立的目录 sources/handover/，不要与 sources/draft/ 混在一起。原因：draft 是等待审批的提案，handover 是尚未完成的进行中工作；两者的生命周期和读者不同。放在一起的话，下次会话就得先筛选。（R5 只检查一级子目录，因此 sources/handover/ 符合要求。）

必须包含以下七个部分，顺序如下：

部分	必须包含的内容
先阅读	1–2 个指向基础概念/ADR 的链接。此文件只说明接下来做什么，不重复介绍架构
后续工作	编号列出。每项工作包含：证据 · 排在此处的原因 · ⏱ 估算 · 风险。阻塞步骤要明确标记为阻塞
小项清理工作	随时可做，合并估算总时间
未解决但不阻塞的问题	表格：工作 · 状态。包括尚未完成测量的事项
陷阱	编号列出。每项包含：现象 → 原因 → 再次遇到时的后果
已尝试并放弃	已排除的方案 + 原因。缺少此部分，下次会话就会原样重试
来源	来源、本次会话中的 commit、相关概念

4. 使用具体单位估算时间

~30 phút · ~2 giờ · nửa ngày — 不要使用“一会儿”“挺快的”。估算错误也好过估算含糊：下次会话看到“半天”，就知道不能塞进当天最后 20 分钟。

5. 检查文件是否可独立阅读

重新阅读并自问：从未参加过本次会话的人能开始工作吗？ 需要追问的地方就是缺漏。尤其要检查：

• 文件路径是否准确（复制粘贴后可直接运行）
• 是否明确说明数字是基于什么测量的（“基于 8 个已更改文件”，而不是“基于几个文件”）
• 是否有地方写了“如上所述”，但没有可供参照的“上文”

6. 登记

在 llmwiki/wiki/index.md 中添加一行，并在 llmwiki/wiki/log.md 末尾追加内容。如果 repo 有 validator：运行 index_sync，直到检查通过。

分支

ID	类型	条件	行为	跳过/失败	重新汇合
B01	可选能力	repo 有 medic	在 W01 中运行 python3 fdk/tools/medic.py --ci	没有 → 跳过	W02
B02	可选能力	repo 有 validator	在 W06 中运行 index_sync，直到检查通过	没有 → 跳过	结束

验证与停止

W05 自检是关卡：未参加本次会话的人必须能够开始工作。“已尝试并放弃”部分为必填；所有程度类描述都必须附带数字。文件登记到索引 + 日志后即可停止。

Examples

• Positive: hết phiên khi đang đối chiếu travel-policy.yaml ↔ install-harness.sh → W01 lấy dòng lệch thật (install-harness.sh:128 vs travel-policy.yaml:71), W02 đánh nó là bước 0 CHẶN, file có đủ 7 mục + ⏱ ~1 giờ, đăng ký index + log (xem ví dụ mở đầu bên dưới).
• Boundary/failure: user nói "bàn giao" cho task đã có SPEC duyệt và rõ từng bước → không viết handover, chuyển plan; hoặc bản nháp ghi "grep chậm" không số → RULE-01 buộc thêm số đo hoặc xoá câu.

Ví dụ mở đầu đạt yêu cầu

### 0. `travel-policy.yaml` phải khớp `install-harness.sh` — CHẶN mọi việc dưới

Bằng chứng nó sai ngay lúc này:
    install-harness.sh:128   cp fdk/tools/build-capabilities.py → ~/.claude/hooks/
    travel-policy.yaml:71    build-capabilities.py → TẦNG 3 FRAMEWORK-ONLY

Installer copy xuống. Hợp đồng khai ở lại.
Hệ quả nếu bỏ qua: mọi câu trả lời "cái gì travel" đều chưa kiểm chéo.
⏱ ~1 giờ cho validator đối chiếu hai bên.

Đọc xong biết ngay: sai ở đâu, chứng minh thế nào, bỏ qua thì mất gì, tốn bao lâu.