fable-handoff

Fable 引き継ぎ

会話全体を再生したり、リポジトリを再調査したりしなくても、別のエージェントが作業を再開できるだけの、検証済みのコンテキストを残します。

ミッション

引き継ぎは要約ではありません。作業再開のための契約です。

引き継ぎを受けるエージェントは、何が依頼され、実際に何が変更され、どの主張が証明済みで、どの証拠が古いか、または不足しているか、現在何がブロックされているか、そして次に取るべき最初の安全なアクションを把握できる必要があります。

使用する状況

• 長時間のタスクを一時停止するとき；
• 別のエージェント／人間／セッションに作業を引き継ぐとき；
• コンテキストが大きくなり、永続的な形で圧縮する必要があるとき；
• リリース／PR が未完了のまま、作業を停止する必要があるとき；
• 自動化／共同作業のループに、永続的なチェックポイントが必要なとき。

使用しない状況

• 簡単な完了ターン以外に、残すべき永続的な情報がないとき；
• 計画や診断が未完了で、次のアクション自体が不明確なとき；
• 未検証の事項や未解決の失敗を隠すために引き継ぎを使うとき。

継続性の分類

状態	引き継ぎで重視すること
クリーンに完了したカード	正確な証拠＋次のカード
変更のあるワークツリー	自分が行った変更と無関係な変更の区別＋安全な再開地点
失敗した試行	再現方法、試したこと、見直した仮説／残る仮説
レビュー待ち	差分／ベース、指摘事項、検証状況
リリース待ち	候補 SHA／バージョン、各チャネルの状態、外部ブロッカー
調査／発見待ち	測定済みの事実、未解決の重要な問い
委任した作業の返答待ち	担当者、返却された／不足している報告

プロトコル

ステージ 1 — 永続化すべきタスクを再構成する

当初／現在のユーザーが望む結果を、簡潔な文で記録します。その内容と、後から判明した実装上の方針を分けます。

ステージ 2 — リポジトリ／作業の状態を正確に記録する

わかる範囲で、次を記録します。

• ブランチ／ワークツリーと候補コミット SHA；
• 進行中のカード／フェーズ；
• 意図的に変更したファイル／領域；
• 保持する必要がある、無関係なユーザー変更；
• 意図的にコミットしない生成物／状態ファイル；
• オープン中の PR／issue／リリース／タグの識別子。

ステージ 3 — 事実、決定、推測を分ける

それぞれを別の区分に記録します。

• 測定済みの事実：リポジトリ／ランタイム／プロバイダーで観測された証拠；
• 決定：選択したアーキテクチャ／契約とその理由；
• 推論：もっともらしいが、まだ証明されていないこと；
• 却下した仮説：失敗した推論を繰り返さないための記録；
• 未解決の問い：次のアクションを変えうるものに限ります。

ステージ 4 — 鮮度を添えて証拠を記録する

重要な主張ごとに、次を記録します。

• コマンド／調査／情報源；
• 結果；
• 関連する変更／コミット／生成物；
• fresh（最新）、stale（古い）、**not checked（未確認）**のいずれか。

NOT_CHECKED を PASS のように見える表現に置き換えてはいけません。

ステージ 5 — 失敗と修復の試みを記録する

引き継ぐ側にとって学びのある試みだけを含めます。何を試し、何が起き、その結果、仮説がどう変わったか、または変わらなかったかを示します。

ステージ 6 — ブロッカーを具体的に示す

ブロッカーには、不足している外部情報／権限／環境と、それが解決した場合に可能になることを明記します。

悪い例：CI issue

良い例：リポジトリで Dependency Graph が無効になっているため、GitHub Dependency Review が失敗します。コード／セキュリティスキャンでは、依存関係の脆弱性は報告されていません。

ステージ 7 — 次に取る安全なアクションを1つ示す

最初の次のアクションは、現在の証拠に基づき、実行可能である必要があります。独立した作業が複数ある場合は、優先するアクションを示した後に列挙します。

ステージ 8 — サニタイズする

シークレット、トークン、秘密鍵、生の認証情報、不要な個人情報、大量のログをコピーしないでください。値を記載する代わりに、安全な認証情報の仕組みに言及してください。

判断ルール

• 説明文より、正確な識別子（ブランチ、SHA、PR、ファイルパス、コマンド）を優先します。
• 否定的な知見も保持します。否定された仮説があれば、同じ無駄を繰り返さずに済みます。
• 圧縮後も証拠の鮮度を維持します。以前成功したテストを、現在も成功しているかのように要約してはいけません。
• 作業ツリーに変更がある場合、タスクに属する変更と、無関係な変更やユーザーが所有する変更を区別します。
• 次のアクションが未解決の判断に左右される場合、引き継ぎ用のアクションを勝手に考えるのではなく、まず計画の再検討または復旧に進みます。
• 会話履歴は補足情報として任意です。引き継ぎ内容だけで完結する必要があります。
• エラーの特徴、コマンド、重要な行があれば十分な場合、ログ全体をコピーしないでください。

不変条件

• 引き継ぎでは、証明されたこととされていないことを正確に伝えます。
• 引き継ぎを受けるエージェントが、名前やブランチを推測せずに該当する作業を正確に特定できます。
• 秘密情報を引き継ぎに保存しません。
• 無関係なユーザーの変更を明示的に保護します。
• 次のアクションで、引き継ぎに記載されていないコンテキストが暗黙に必要にならないようにします。

失敗の分類

物語の垂れ流し

会話の経緯が多すぎて、実行可能な状態の情報が少なすぎます。タスク、状態、証拠、次のアクションを中心に再構成します。

鮮度の誤認

古い証明を現在のものとして要約しています。変更内容、SHA、成果物のコンテキストを添え、古くなった証拠の確度を下げます。

コンテキスト不足

引き継ぎ先がアーキテクチャや判断理由を再調査しなければなりません。重要な証拠や判断理由を、必要最小限の範囲で追加します。

秘密情報の漏えい

認証情報が要約やログに含まれています。値を削除し、安全な参照先だけを記載します。

所有者の曖昧さ

変更のあるファイルを列挙しているものの、それぞれがタスク、ユーザー、または別の作業のどれに属するかを示していません。引き継ぎ前に明確にします。

完了の偽装

外部のゲート、レビュー、プロバイダーの証拠が不足しているのに、引き継ぎで「完了」としています。保留中またはブロック中の状態を明示します。

アンチパターン

• 会話全体をコピーすること。
• 解釈を加えずにターミナル出力をそのまま貼り付けること。
• 失敗した試行を省略し、次のエージェントに同じ試行を繰り返させること。
• コミットや変更の鮮度を示さずに「テストに合格した」と述べること。
• 「次のエージェントに必要だから」という理由でトークンを保存すること。
• 「修正を続ける」のような曖昧な次の手順を書くこと。
• 実装に重要なユーザーの制約や好みを失わせること。
• 準備済みの成果物しかないのに、リリースまたは公開済みと主張すること。

引き継ぎパケット

Goal:
Current branch/worktree/SHA:
Active phase/card:
Intentional changes:
Protected unrelated changes:
Measured facts:
Decisions + rationale:
Rejected hypotheses / failed attempts:
Evidence:
- claim → command/source → result → fresh/stale/not checked
Open findings/blockers:
External states (PR/CI/release/registry):
Primary next safe action:
Secondary independent actions:
Do not repeat / do not change:

完了基準

コンテキストがまったくないエージェントでも、次のことができれば引き継ぎは完了です。

• 正確なタスクとリポジトリの状態を特定する。
• 事実、判断、推論を区別する。
• どの証拠が新しいかを把握する。
• 否定された試行を繰り返さずに済む。
• 無関係な作業と認証情報を安全に保護する。
• 基本的な情報の不足について質問せずに、次のアクションを実行する。

段階的なリソース

• 詳細ガイド：references/resumability-and-context-compaction.md
• 既存のスキーマ：references/continuity-schema.md
• テンプレート：templates/handoff-state.template.md
• 例：examples/cross-session-handoff.md