Back to Details

orca-handover

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Skill: orca-handover

Skill: orca-handover

WHAT

是什么

Purpose và context

目的与上下文

  • Purpose: sinh MỘT file 
    .md
    bàn giao tự đứng được để phiên khác (không có context) mở ra là làm tiếp được: việc còn dở, thứ tự có lý do, số đo làm bằng chứng, cạm bẫy, nợ mở.
  • Trigger (when to use):
    • Phiên dài sắp kết thúc mà việc chưa xong, và phiên sau không có context nào.
    • Vừa điều tra ra một chuỗi phát hiện, cần chốt lại thứ tự giải trước khi quên lý do.
    • Chuyển việc cho người/agent khác mà việc còn mơ hồ (chưa có SPEC duyệt).
  • Non-goals (KHÔNG dùng khi):
    • Task đã duyệt và đã rõ từng bước → dùng 
      plan
      (brief thi hành cho agent headless).
    • Chỉ cần máy truy hồi "phiên trước làm gì" → dùng 
      record-episode
      (mem-rank).
    • Chuyển quyền sở hữu worktree/terminal cho agent khác → dùng 
      orca-cli
      (full handoff).
  • 目的： 生成一个自包含的 
    .md
    交接文件，让另一个没有 context 的 session 打开后即可继续工作：包括未完成的工作、有理由的顺序、可作为证据的指标、陷阱以及未结事项。
  • 触发条件（何时使用）：
    • 长 session 即将结束，但工作尚未完成，而且后续 session 没有任何 context。
    • 刚刚调查出一系列发现，需要在遗忘原因之前确定解决顺序。
    • 将仍不明确的工作移交给其他人或 agent（尚无已批准的 SPEC）。
  • 非目标（不要在以下情况使用）：
    • Task 已批准且每个步骤都清楚 → 使用 
      plan
      （给 headless agent 的执行 brief）。
    • 只需要机器检索“上一个 session 做了什么” → 使用 
      record-episode
      （mem-rank）。
    • 将 worktree/terminal 的所有权移交给其他 agent → 使用 
      orca-cli
      （完整交接）。

Mental model

心智模型

bằng chứng chạy thật (git log/status, medic) → việc còn lại → quan hệ CHẶN → file 7 mục trong sources/handover/ → index + log
.
真实运行证据（git log/status、medic）→ 剩余工作 → 阻塞关系 → sources/handover/ 中的七章节文件 → index + log
。

Nguyên tắc — vì sao file này khác một bản tóm tắt

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

Người đọc nó không có gì cả: không transcript, không biết hôm qua đã thử gì và vì sao bỏ. Tóm tắt kể đã làm gì; bàn giao phải trả lời làm gì tiếp và vì sao thứ tự đó.
Ba thứ quyết định file này dùng được hay không:
  1. Mỗi claim phải có SỐ ĐO. "Grep không đủ tốt" là ý kiến. "Trên 8 file đổi: grep nghi 36, graph 25, trùng 21 ⇒ thừa 15 sót 4" là bằng chứng — phiên sau kiểm lại được, và không phải tin lời ai.
  2. Thứ tự phải có LÝ DO, và phải chỉ rõ cái nào CHẶN cái nào. Danh sách phẳng khiến phiên sau chọn việc dễ nhất trước rồi vấp cái chưa xong.
  3. Cạm bẫy là phần đắt nhất. Mỗi lỗi đã trả giá mà không ghi lại thì phiên sau trả giá lần nữa.
阅读者什么也没有：没有 transcript，不知道昨天尝试过什么，也不知道为什么放弃。摘要讲述做过什么；交接必须回答接下来做什么，以及为什么是这个顺序。
有三件事决定这个文件是否可用：
  1. 每一项结论都必须有指标。“Grep 不够好”是意见。“在 8 个变更文件上：grep 漏掉 36 个、graph 漏掉 25 个、重复 21 个 ⇒ 多出 15 个、漏掉 4 个”才是证据——后续 session 可以重新验证，而不必相信任何人的说法。
  2. **顺序必须有理由，并且必须明确谁阻塞谁。**扁平列表会让后续 session 先挑最容易的工作，随后被尚未完成的事项绊住。
  3. **陷阱是最昂贵的部分。**每个没有记录的错误，都会让后续 session 再次付出同样的代价。

Input và output contract

输入与输出契约

FieldRequired?Ý nghĩa
Intrạng thái phiên (repo, việc còn dở, phát hiện)cólấy qua lệnh chạy thật, không theo trí nhớ
Inconcept/ADR nềnkhôngđể link ở mục "Đọc trước" thay vì chép lại
Out
llmwiki/wiki/sources/handover/DDMMYY-<tên>.md
cóbảy mục đúng thứ tự (bảng ở W03)
Outdòng trong 
llmwiki/wiki/index.md
+ append 
llmwiki/wiki/log.md
cóđăng ký; 
index_sync
xanh nếu repo có validator
字段必需？含义
Insession 状态（repo、剩余工作、发现）是通过实际运行的命令获取，不依赖记忆
In基础 concept/ADR否在“必读”章节中提供链接，而不是重复抄写
Out
llmwiki/wiki/sources/handover/DDMMYY-<tên>.md
是按 W03 中的表格排列七个章节
Out
llmwiki/wiki/index.md
中的一行，并向 
llmwiki/wiki/log.md
追加内容		是登记；如果 repo 有 validator，则 
index_sync
应为绿色

Rules và capabilities

规则与能力

  • RULE-01 (MUST): Số đo > tính từ. Mọi phát biểu về mức độ ("chậm", "nhiều", "hỏng nặng") phải kèm số hoặc bị xoá.
  • RULE-02 (MUST): Đường dẫn tuyệt đối hoặc repo-relative chính xác — phiên sau copy-paste là chạy, không phải đoán thư mục.
  • RULE-03 (MUST): Không lặp lại kiến trúc — link tới concept đã có. File bàn giao phình lên vì chép lại nền là file không ai đọc hết.
  • RULE-04 (MUST): Ghi cả cái CHƯA xác minh — "chưa đo", "chưa kiểm chéo" là thông tin quý; giấu nó khiến phiên sau xây trên nền giả định.
  • RULE-05 (MUST): Mục "Đã thử và BỎ" không được thiếu — đây là mục dễ quên nhất và tốn nhất khi thiếu.
  • RULE-06 (MUST): KHÔNG chép transcript. Bàn giao là chắt lọc, không phải log. Dài quá 200 dòng là dấu hiệu đang chép thay vì chắt.
  • RULE-07 (MUST): Anti-pattern: viết "tiếp tục công việc dang dở" mà không nói dang dở ở đâu, file nào, dòng nào.
  • Capabilities: đọc trạng thái repo + chạy gate sức khoẻ cục bộ (read-only); ghi một file trong wiki + index + log.
  • RULE-01 (MUST)：**指标 > 形容词。**每项关于程度的陈述（“慢”“很多”“严重损坏”）都必须附带数字，否则删除。
  • RULE-02 (MUST)：使用绝对路径或精确的 repo-relative 路径——后续 session 应该能够直接 copy-paste 运行，而不是猜测目录。
  • RULE-03 (MUST)：不要重复架构——链接到已有 concept。交接文件之所以臃肿，是因为重复抄写背景，导致没人能读到结尾。
  • RULE-04 (MUST)：也要记录尚未验证的内容——“未测量”“未交叉验证”是宝贵信息；隐藏它会让后续 session 建立在假设之上。
  • RULE-05 (MUST)：“已尝试并放弃”章节不得缺失——这是最容易忘记、缺失后代价也最高的章节。
  • RULE-06 (MUST)：**不要抄写 transcript。**交接是筛选后的结果，不是日志。超过 200 行通常意味着你在抄写，而不是筛选。
  • RULE-07 (MUST)：避免这种 anti-pattern：只写“继续未完成的工作”，却不说未完成在哪里、涉及哪些文件、具体到哪些行。
  • 能力：读取 repo 状态并运行本地健康检查 gate（read-only）；在 wiki 中写入一个文件，并更新 index + log。

Failure boundaries

失败边界

  • Số không tái lập được bằng lệnh → không bịa: ghi rõ chưa xác minh (partial hợp lệ).
  • Việc thật ra đã rõ + đã duyệt → clarify/chuyển 
    plan
    ; chỉ cần truy hồi máy → 
    record-episode
    .
  • File không tự đứng được (phải hỏi lại, path sai, "như đã bàn ở trên") → failed tự kiểm W05, sửa rồi kiểm lại.
  • Dài quá 200 dòng → dấu hiệu đang chép transcript, cắt lại.
  • 无法通过命令复现的数字 → 不得编造：明确标注为尚未验证（属于有效的部分结果）。
  • 工作实际上已经明确且已批准 → 使用 clarify／转交 
    plan
    ；只需要机器检索 → 使用 
    record-episode
    。
  • 文件无法自包含（必须再次询问、路径错误、写有“如上文所述”）→ 标记为 failed，执行 W05 自检，修复后重新检查。
  • 超过 200 行 → 这是抄写 transcript 的迹象，需要精简。

HOW

如何执行

Main workflow

主工作流

StepTypeInputsActionOutputs/exitFailure/next
W01deterministicrepoThu bằng chứng TRƯỚC khi viết (
git log
, 
git status
, medic nếu có)		số đo thậtkhông tái lập được → ghi "chưa xác minh"
W02judgmentviệc còn lạiXác định cái CHẶN (làm B trước A thì hỏng gì?)bước 0 + thứ tự có lý dokhông có quan hệ → ghi "thứ tự tự do"
W03effectW01–W02Viết 
llmwiki/wiki/sources/handover/DDMMYY-<tên>.md
bảy mục		file handover—
W04judgmenttừng việcƯớc lượng thời gian bằng đơn vị cụ thể⏱ mỗi việc—
W05judgmentfileKiểm file tự đứng được (path chính xác, số nói rõ đo trên gì, không "như trên")file đạtthiếu → sửa, lặp W05
W06effectfileĐăng ký index + log; 
index_sync
nếu có validator		index/log khớpvalidator đỏ → sửa
Chi tiết từng bước (nguồn chân lý cho W01–W06):
StepTypeInputsActionOutputs/exitFailure/next
W01deterministicrepo写作前收集证据（
git log
、
git status
，如有则运行 medic）		真实指标无法复现 → 标注“尚未验证”
W02judgment剩余工作确定阻塞项（先做 B 而非 A 会破坏什么？）步骤 0 + 有理由的顺序无依赖关系 → 标注“顺序自由”
W03effectW01–W02编写包含七个章节的 
llmwiki/wiki/sources/handover/DDMMYY-<tên>.md
handover 文件—
W04judgment每项工作使用具体单位估算时间每项工作的 ⏱ 估算—
W05judgment文件检查文件能否自包含（路径准确、数字注明测量对象、没有“如上文所述”）文件通过缺失 → 修复并重复 W05
W06effect文件登记 index + log；如有 validator，则运行 
index_sync
index/log 一致validator 为红色 → 修复
以下各步骤的详细信息是 W01–W06 的真实来源：

1. Thu bằng chứng TRƯỚC khi viết (đừng viết theo trí nhớ)

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

bash
git log --oneline -15
git status --short
python3 fdk/tools/medic.py --ci 2>&1 | tail -5     # nếu repo có medic
Mọi con số trong file phải lấy từ lệnh chạy thật trong phiên, không ước lượng lại. Số nào không tái lập được thì ghi rõ là chưa xác minh, đừng làm tròn thành sự thật.
bash
git log --oneline -15
git status --short
python3 fdk/tools/medic.py --ci 2>&1 | tail -5     # nếu repo có medic
文件中的每个数字都必须来自 session 中实际运行的命令，不能再次估算。无法复现的数字必须明确标为尚未验证，不能通过四舍五入将其变成事实。

2. Xác định cái CHẶN

2. 确定阻塞项

Với mỗi việc còn lại, hỏi: làm việc B trước việc A thì hỏng gì? Có câu trả lời cụ thể → A là bước 0, ghi kèm hậu quả nếu bỏ qua. Không có → thứ tự tự do, nói luôn là tự do.
对于每项剩余工作，询问：*如果先做 B 而非 A，会破坏什么？*如果答案具体，则 A 是步骤 0，并记录跳过它的后果。如果没有答案，则顺序自由，并明确说明这一点。

3. Viết file 
llmwiki/wiki/sources/handover/DDMMYY-<tên>.md

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

Thư mục riêng 
sources/handover/
— không trộn vào 
sources/draft/
. Lý do: draft là đề xuất chờ duyệt, handover là việc đang chạy dở; hai loại có vòng đời khác nhau và người đọc khác nhau. Gom chung thì phiên sau phải lọc. (R5 chỉ kiểm subfolder cấp một nên 
sources/handover/
hợp lệ.)
Bảy mục, đúng thứ tự này:
MụcNội dung bắt buộc
Đọc trước1–2 link tới concept/ADR nền. File này chỉ nói làm gì tiếp, không lặp lại kiến trúc
Việc tiếp theoĐánh số. Mỗi việc: bằng chứng · vì sao ở vị trí này · ⏱ ước lượng · rủi ro. Bước chặn ghi rõ CHẶN
Việc dọn nhỏLàm lúc nào cũng được, gộp ước lượng chung
Nợ mở, không chặnBảng: việc · trạng thái. Gồm cả thứ đo chưa xong
Cạm bẫyĐánh số. Mỗi cái: hiện tượng → nguyên nhân → hậu quả nếu dính lại
Đã thử và BỎHướng đã loại + lý do. Thiếu mục này phiên sau sẽ thử lại y hệt
OriginNguồn, commit trong phiên, concept liên quan
使用独立的 
sources/handover/
目录——不要与 
sources/draft/
混用。原因是：draft 是等待批准的提案，handover 是正在进行的工作；两者具有不同的生命周期和读者。混在一起会迫使后续 session 自行筛选。（R5 只检查一级 subfolder，因此 
sources/handover/
是有效的。）
七个章节必须严格按以下顺序排列：
章节必需内容
必读1–2 个指向基础 concept/ADR 的链接。此文件只说明接下来做什么，不要重复架构
后续工作编号列出。每项工作：证据 · 为什么处于这个位置 · ⏱ 估算 · 风险。阻塞步骤必须明确标记为 CHẶN
小型清理工作任何时候都可以执行的工作，合并给出估算
未结事项，不阻塞表格：工作 · 状态。包括尚未测量的事项
陷阱编号列出。每项包含：现象 → 原因 → 再次遇到时的后果
已尝试并放弃已排除的方向 + 原因。缺少此章节，后续 session 会再次尝试完全相同的方案
来源（Origin）来源、session 中的 commit、相关 concept

4. Ước lượng thời gian bằng đơn vị cụ thể

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

~30 phút
· 
~2 giờ
· 
nửa ngày
— không dùng "một chút", "khá nhanh". Ước sai còn hơn ước mơ hồ: phiên sau đọc "nửa ngày" thì biết không nhét vào 20 phút cuối ngày.
~30 分钟
· 
~2 小时
· 
半天
——不要使用“一点点”“相当快”。即使估算不准，也比含糊不清更好：后续 session 看到“半天”时，就知道它无法塞进当天最后 20 分钟。

5. Kiểm file tự đứng được

5. 检查文件能否自包含

Đọc lại và tự hỏi: người chưa từng dự phiên này có bắt đầu được không? Chỗ nào phải hỏi lại là chỗ thiếu. Đặc biệt kiểm:
  • Đường dẫn file có chính xác không (copy-paste chạy được)
  • Con số có nói rõ đo trên cái gì không ("trên 8 file đổi" chứ không phải "trên vài file")
  • Có chỗ nào viết "như đã bàn ở trên" mà không có "trên" không
重新阅读并自问：**从未参与这个 session 的人能否直接开始？**任何需要再次询问的地方，都是缺失的信息。特别检查：
  • 文件路径是否准确（copy-paste 后可以直接运行）
  • 数字是否注明了测量对象（写“在 8 个变更文件上”，而不是“在几个文件上”）
  • 是否存在“如上文所述”，却没有任何“上文”

6. Đăng ký

6. 登记

Thêm dòng vào 
llmwiki/wiki/index.md
, append 
llmwiki/wiki/log.md
. Nếu repo có validator: chạy 
index_sync
cho xanh.
在 
llmwiki/wiki/index.md
中添加一行，并向 
llmwiki/wiki/log.md
追加内容。如果 repo 有 validator：运行 
index_sync
，确保结果为绿色。

Branches

Branches

IDKindGuardHành viSkip / failureRejoin
B01capability_optionalrepo có medicchạy 
python3 fdk/tools/medic.py --ci
trong W01		không có → bỏ quaW02
B02capability_optionalrepo có validatorchạy 
index_sync
cho xanh ở W06		không có → bỏ quakết thúc
IDKindGuard行为Skip / failureRejoin
B01capability_optionalrepo 有 medic在 W01 中运行 
python3 fdk/tools/medic.py --ci
没有 → 跳过W02
B02capability_optionalrepo 有 validator在 W06 中运行 
index_sync
，确保结果为绿色		没有 → 跳过结束

Validation và stopping

验证与停止条件

Tự kiểm W05 là cổng: người chưa dự phiên phải bắt đầu được. Mục "Đã thử và BỎ" bắt buộc có; mọi tính từ mức độ đều kèm số. Dừng khi file đã đăng ký index + log.
W05 自检是一道 gate：从未参与该 session 的人必须能够开始工作。“已尝试并放弃”章节必须存在；所有程度形容词都必须附带数字。当文件已经登记到 index + log 后停止。

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.
  • **正向示例：**在对照 
    travel-policy.yaml
    ↔ 
    install-harness.sh
    时 session 即将结束 → W01 获取真实差异位置（
    install-harness.sh:128
    与 
    travel-policy.yaml:71
    ），W02 将其标记为阻塞其余工作的步骤 0，文件包含全部 7 个章节及 ⏱ ~1 小时，并登记 index + log（见下方示例开头）。
  • **边界/失败：**当 user 要求为已有已批准 SPEC 且每个步骤都清楚的任务进行“bàn giao” → 不编写 handover，而是转交 
    plan
    ；或者草稿只写了“grep 慢”却没有数字 → RULE-01 强制补充指标或删除该句。

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

符合要求的开头示例

markdown
undefined
markdown
undefined

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

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.
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.

读完后立刻可以知道：哪里有问题、证据是什么、跳过会损失什么，以及需要多长时间。