orca-handover

スキル：orca-handover

概要

目的とコンテキスト

• 目的： 別のセッション（コンテキストなし）が開けばすぐ作業を続けられる、自立した .md 引き継ぎファイルを1つ作成します。未完了の作業、理由のある順序、証拠となる測定値、落とし穴、未解決の課題を記載します。
• 使用するタイミング：
  • 長時間のセッションが終わりそうで、作業が未完了かつ、次のセッションにコンテキストがまったくない場合。
  • 一連の発見を調査し終え、理由を忘れる前に解決する順序を確定する必要がある場合。
  • 作業がまだ曖昧な状態（承認済みの SPEC がない状態）で、別の人やエージェントに引き継ぐ場合。
• 対象外（使用しない場合）：
  • タスクが承認済みで、手順も明確な場合 → plan を使います（ヘッドレスエージェント向けの実行ブリーフ）。
  • 「前のセッションで何をしたか」をマシンに検索させるだけの場合 → record-episode（mem-rank）を使います。
  • worktree／ターミナルの所有権を別のエージェントに移す場合 → orca-cli を使います（完全な引き継ぎ）。

メンタルモデル

実行時の証拠（git log/status、medic）→ 残作業 → ブロック関係 → sources/handover/ の7項目ファイル → index + log

原則 — このファイルが単なる要約と異なる理由

読む人には何もありません。トランスクリプトもなく、昨日何を試し、なぜやめたのかもわかりません。要約は何をしたかを伝えます。引き継ぎは次に何をするか、なぜその順序なのかに答える必要があります。

このファイルが役立つかどうかを決めるのは、次の3点です。

1. すべての主張に測定値を付けること。「Grep は十分ではない」は意見です。「変更した8ファイルで、Grep は36件を疑い、グラフは25件、重複は21件 ⇒ 15件過剰、4件見落とし」は証拠です。次のセッションで再確認でき、誰かの言葉を信じる必要もありません。
2. 順序には理由を付け、何が何をブロックするかを明記すること。 単なる箇条書きでは、次のセッションが最も簡単な作業から始め、未完了の項目でつまずく可能性があります。
3. 最も価値が高いのは落とし穴です。 すでに代償を払った失敗を記録しなければ、次のセッションも同じ代償を払うことになります。

入力と出力の契約

	フィールド	必須？	意味
入力	セッションの状態（repo、残作業、発見事項）	はい	記憶を頼らず、実行コマンドで取得します
入力	基礎となるコンセプト／ADR	いいえ	内容を転記せず、「事前に読む」項目にリンクします
出力	llmwiki/wiki/sources/handover/DDMMYY-<tên>.md	はい	正しい順序の7項目（一覧は W03）
出力	llmwiki/wiki/index.md の1行 + llmwiki/wiki/log.md への追記	はい	登録します。repo にバリデーターがある場合、index_sync が緑であること

ルールと機能

• RULE-01（MUST）：形容詞より測定値。 程度を表す記述（「遅い」「多い」「ひどく壊れている」）には、必ず数値を付けるか、記述を削除します。
• RULE-02（MUST）：絶対パスまたは正確な repo 相対パスを記載すること — 次のセッションでコピー＆ペーストして実行できるようにし、ディレクトリを推測させないでください。
• RULE-03（MUST）：アーキテクチャを繰り返さないこと — 既存のコンセプトにリンクします。基礎情報を転記して膨らんだ引き継ぎファイルは、最後まで読まれません。
• RULE-04（MUST）：未検証の内容も記録すること —「未測定」「クロスチェック未実施」は貴重な情報です。隠すと、次のセッションが誤った前提の上に作業を進めてしまいます。
• RULE-05（MUST）：「試してやめたこと」の項目を省略しないこと — 最も忘れやすく、省略すると最もコストがかかる項目です。
• RULE-06（MUST）：トランスクリプトを転記しないこと。 引き継ぎは要点を抽出したものであり、ログではありません。200行を超える長さは、要点の抽出ではなく転記している兆候です。
• RULE-07（MUST）：アンチパターン：「未完了の作業を続ける」とだけ書き、どこまで未完了なのか、どのファイルのどの行なのかを示さないこと。
• 機能：repo の状態を読み取り、ローカルのヘルスチェックゲートを実行する（読み取り専用）。wiki に1つのファイルを書き込み、index と log を更新する。

失敗の境界

• コマンドで再現できない数値は捏造せず、未検証と明記します（部分的な状態でも有効です）。
• 作業が実際には明確で承認済みの場合は、clarifyしてplanに移行します。マシンに検索させるだけの場合は、record-episodeを使います。
• ファイルだけでは自立できない（再質問が必要、パスが間違っている、「上で話したとおり」といった記述がある）場合は、W05 の自己チェックで失敗と判断し、修正してから再確認します。
• 200行を超える長さは、トランスクリプトを転記している兆候です。内容を絞り込んでください。

手順

メインワークフロー

ステップ	種類	入力	アクション	出力／終了条件	失敗時／次
W01	決定的	repo	書く前に証拠を収集する（git log、git status、あれば medic）	実測値	再現できない → 「未確認」と記録
W02	判断	残作業	何がブロック要因かを特定する（BをAより先に行うと、何が壊れるか？）	ステップ0＋理由のある順序	関係がない → 「順序は自由」と記録
W03	効果	W01–W02	llmwiki/wiki/sources/handover/DDMMYY-<tên>.md に7項目を記述する	handover ファイル	—
W04	判断	各作業	具体的な単位で所要時間を見積もる	各作業に ⏱	—
W05	判断	ファイル	ファイル単体で内容が通じるか確認する（正確なパス、数値の測定対象を明記、「前述のとおり」は使わない）	合格したファイル	不足 → 修正し、W05を繰り返す
W06	効果	ファイル	index と log に登録する。validator があれば index_sync を実行する	index／log が一致	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 は第1階層のサブフォルダーのみを確認するため、sources/handover/ は有効です。）

次の7項目を、指定の順番で記載します。

項目	必須内容
先に読む	基盤となる concept／ADR へのリンクを1～2件。このファイルでは 次に何をするか だけを述べ、アーキテクチャを繰り返さない
次の作業	番号付きリストにする。各作業に、証拠・この位置にある理由・⏱ 見積もり・リスクを記載する。ブロック要因となるステップには ブロック と明記する
小さな後片付け	いつでもできる作業を記載し、見積もりはまとめる
ブロックしない未解決の負債	作業・状態の表。測定がまだ完了していない項目も含める
落とし穴	番号付きリストにする。各項目に、現象 → 原因 → 再発した場合の影響を記載する
試したが却下したこと	却下した方法＋理由。この項目がないと、次のセッションでまったく同じことを再度試してしまいます
Origin	出典、このセッションでのコミット、関連する concept

4. 具体的な単位で所要時間を見積もる

~30 phút · ~2 giờ · nửa ngày のように記載し、「少し」「かなり早く」は使わないでください。曖昧な見積もりより、外れる見積もりのほうが役に立ちます。次のセッションで「半日」と読めば、1日の最後の20分には収まらないとわかります。

5. ファイル単体で内容が通じるか確認する

読み返して、次のように自問してください。このセッションに参加していない人でも作業を始められるか？ 確認が必要な箇所は、情報が不足しています。特に次の点を確認してください。

• ファイルのパスは正確か（コピー＆ペーストして実行できるか）
• 数値について、何を対象に測定したかが明記されているか（「数ファイル」ではなく「変更した8ファイル」）
• 「上で話したとおり」と書かれているのに、その「上」がない箇所はないか

6. 登録する

llmwiki/wiki/index.md に行を追加し、llmwiki/wiki/log.md に追記します。repo に validator がある場合は、index_sync を実行して成功させます。

分岐

ID	種類	条件	動作	スキップ／失敗	再合流
B01	capability_optional	repo に medic がある	W01 で python3 fdk/tools/medic.py --ci を実行する	なければ → スキップ	W02
B02	capability_optional	repo に validator がある	W06 で index_sync を実行して成功させる	なければ → スキップ	終了

検証と終了条件

W05 の自己確認をゲートとします。このセッションに参加していない人が作業を始められることが条件です。「試したが却下したこと」の項目は必須です。程度を表す形容詞には、すべて数値を添えてください。ファイルを 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.

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.