resume-handoff

引き継ぎから再開する

前のセッションは、まだ残作業がある状態で終了し、docs/<feature>/HANDOFF.md（別の場所を使用していなければ、プロジェクトの計画フォルダー内）を残しています。前の会話は一切ありません。手元にあるのは、ツリー、引き継ぎドキュメント、およびそこから参照されているドキュメントだけです。引き継ぎドキュメントは、何かに手を付ける前に全文を読むことを前提に書かれています。

相反する2つの点で評価されます。最初の1時間は、過去を掘り返すのではなく、有意義な作業に充てること――引き継ぎがあるのは、すでに書かれていることを再び導き出さずに済むようにするためです。そして、引き継ぎを、その内容に見合うだけの信頼度で扱うこと――引き継ぎはある時点での状況を、時間に追われたエージェントが記したものであり、その後に変化したのはツリーだけです。古くなった引き継ぎを信じて再開すると、すでに存在しないブランチの状態を前提に作業することになります。引き継ぎを無視して再開すると、そこに記された落とし穴に何度もはまることになります。

write-handoff スキルには、執筆者が何を記載するよう指示されていたかが書かれています。そのスキルを一度読んでください。ドキュメントに本来何が書かれているべきかを知れば、欠けている内容を確認する際の手がかりになります。

以下では、<main> はメインの統合ブランチ（例：main や dev）を指します。「質問ログ」とは、プロジェクトで未解決の質問を記録している場所を指します（決まった形式がない場合は、計画の近くにある質問セクションまたはファイルです）。

このスキルについて

• このスキル — 受付を担当します。読み、確認し、提案し、質問します。その後、ユーザーの確認を得てからマージし、ドキュメントに合った実行スキルのもとで作業を続けます。このスキルは、機能を完了するのではなく、引き継ぎを行って終わります。
• execute-plan — 受付が終わり、機能に PLAN.final.md がある場合に進む先です。ここで実装します。
• execute-roadmap — 機能に ROADMAP.final.md がある場合、または複数の計画を並行して進める旨が引き継ぎに記載されている場合に進む先です。ブリーフィングとレビューを行います。
• write-handoff — 執筆者側のスキルです。このセッションの終わりに使用します。今回も、ほぼ確実に残作業がある状態で終了するためです。
• close-plan / close-roadmap — 照合の結果、実際には作業範囲が完了しており、引き継ぎが古く、再開すべき作業がない場合に使用します。その旨を伝えて切り替え、次のフェーズを勝手に作り出さないでください。

入力

引数には機能名、任意で作業範囲、任意でモデルまたは作業量の指示を指定します。例：

• /resume-handoff cloud-sync
• /resume-handoff spell-check p4-p5
• /resume-handoff finish the roadmap, high effort for the workers

作業範囲と指示は変更せずに実行スキルへ引き継ぎます。実行スキルに従って解決し、お使いのエージェントツールが対応している場合は、モデルまたは作業量の指示に従ってください。引数が HANDOFF.md へのパスだけの場合、機能名はそのファイルが置かれているフォルダー名です。

何かに手を加える前に読むこと

ツリーを変更する最初のコマンドを実行する前に、次の順番ですべて読んでください。

1. プロジェクトのエージェント向けガイド（AGENTS.md、CONTRIBUTING.md、または類似のファイル）。すべての引き継ぎでは、テストのルール、ドキュメントの構成、作業可能な範囲に関するルールなどを読んでいることが前提となっており、通常は冒頭にその旨が記されています。
2. docs/<feature>/HANDOFF.md の全文。 冒頭だけではありません。落とし穴は後半にあり、読み飛ばした落とし穴に必ずはまります。
3. 引き継ぎで正式な参照先として指定されているドキュメントを、記載された順に。 通常は最終ドキュメント、次に意思決定記録や契約書、続いて EXECUTION.md、最後に質問ログです。「要約は仕様ではない」と書かれている場合は、そのとおりに受け止めてください。構築内容を振り返る引き継ぎの要約文は、ページの中でもっとも誤っている可能性が高い箇所です。書かれた時点で、それはすでに複製されたものだからです。
4. プロジェクトに定められている原則（PRINCIPLES.md または類似のファイル）があればそれを読み、さらに今回の作業で触れるコード領域のドキュメントも読んでください。

改訂版は読まないでください。 PLAN.revN.md と ROADMAP.revN.md は最終ドキュメントに至るまでの履歴です。作業するスキルは最終ドキュメントのみを参照します。引き継ぎで特定の推論について改訂版を参照するよう指示された場合は、その箇所を読んでください。

引き継ぎ内容をツリーと照合する

引き継ぎには複数の主張が含まれています。どれも確認は簡単ですが、誤っていると大きな問題になるため、行動を起こす前にすべて確認してください。これは、close-plan が EXECUTION.md に適用するのと同じルールです。主張であって、事実ではありません。**このセクションとその後の2つのセクションは、すべて読み取り専用です。**ユーザーが提案を確認するまで、ツリーには何も変更を加えません。

現在の場所。 git rev-parse --show-toplevel が、引き継ぎで指定されたチェックアウト、またはその移動先である必要があります。マシンによってドライブ文字やルートは異なります。ここでのルートではないパスは、あなたが編集する対象ではありません。チェックアウト（またはワークツリー）が存在せず、ブランチが存在する場合は、それを作成することが最初の提案になると記録してください。ブランチもローカルに存在せず、引き継ぎに何もプッシュされていないと書かれている場合は、中止してください。作業は別のマシン上にあり、ここから復元することはできません。どのブランチで、どのマシンにあるかをユーザーに伝えてください。

ブランチの状態を、引き継ぎの記述と照合します。

• git status — ツリーはクリーンですか？再開時にツリーがクリーンでなければ、前回のセッションが書き込みの途中で終了したか、その後に誰かが作業した可能性があります。どちらなのか判断する前に差分を確認してください。
• git fetch を実行し、続けて git log --oneline <branch>..<main> と <main>..<branch> を確認します。引き継ぎに記載された先行・遅れの件数は、その日時点では正しかったものです。件数が増えていれば、引き継ぎにあるマージの助言は、より小さな <main> を前提に書かれています。
• git log origin/<branch> — 「プッシュされていない」という状態は今も変わっていませんか？その答えによって、ミスの代償が変わります。
• 引き継ぎで言及されているすべてのコミットハッシュが存在すること（git cat-file -t <hash>）と、最新のコミットが先端付近にあることを確認してください。引き継ぎの日付より後にコミットされたものは、引き継ぎが把握していない作業です。「どこから再開するか」を信頼する前に、それらのコミットを確認してください。

何が構築されたかを、コードと照合します。引き継ぎと EXECUTION.md が完了したとする各フェーズや計画について、コードを開き、最終ドキュメントの検証手順に記載された内容が実現されているか確認してください。フェーズが完了しているのは、コードがその機能を実現しているときであり、3つのドキュメントにそう書かれているときではありません。再開時にすべてのテストスイートを再実行する必要はありません。ただし、確認できなかった主張は、事実ではなく未確認として明記し、引き継いでください。

誰も見ていない間に変わったこと：

• 質問ログ — 引き継ぎの作成後にユーザーが質問へ回答している可能性があり、その回答によって、引き継ぎでブロック中とされたフェーズが進められるようになったり、確定済みとされた判断が覆ったりすることがあります。すべての項目を確認してください。引き継ぎは回答前に作成されています。「ユーザーが Q5 と Q6 に回答した後のセッション向け」のように、この瞬間のために作成された引き継ぎもあります。
• ブロッカー。「別のブランチが <main> に取り込まれるのを待つ」と記された引き継ぎは、その日時点では正しかったものです。実際に取り込まれたか確認してください。解消されたブロッカーによって作業範囲が広がります。未解消のものは、引き継ぎに記された順序がどれほどそれを望んでいても、引き続きブロッカーです。
• **以前からの失敗。**親ブランチで失敗していたテストを引き継ぎが挙げているのは、その問題を追いかけないようにするためです。赤の原因を追う前にも、失敗を見過ごす前にも、親ブランチでそれらのテストを実行するか、最新の CI を確認して、該当リストが今も変わっていないことを確認してください。
• **非公開の記憶。**リポジトリ外の記憶やメモを参照する引き継ぎは、このセッションでは参照できない情報を前提にしている可能性があります。記録となるのはツリーです。その情報が重要なら、引き継ぎかドキュメントに含めてください。最後に次の引き継ぎを書く際に、本文へ記載してください。

確認結果は短い表にまとめてください。列は「主張」「ツリーの状況」「それに対して何を提案するか」です。これが、以下の提案の最初の部分になります。

HANDOFF.md がない場合、あなたは引き継ぎから作業を再開するのではなく、過去の経緯を調査しています。その旨を伝えてください。EXECUTION.md、質問ログ、git log、最終ドキュメントから同じ表を再構成してください。実行スキルは、コミット済みの作業をすでに除外する方法を把握しています。記録されていない落とし穴があることを想定してください。このセッションの最後に、自分が受け取りたかった引き継ぎを作成してください。

マージ内容を確認する

引き継ぎで最初に行うことは、通常、ツリーに何かが加わる前に <main> をマージすることです。実際にはマージせずに、今すぐ内容を確認してください。merge-branch ゲートの「マージ前」の部分です。

• git log --oneline <branch>..<main> と git diff --stat <branch>...<main> を実行し、この機能の基盤となるファイルに触れる差分のハンクを確認します。<main> に何が加わったのか、そのうちこの作業に関係するものはどれか、競合が予想される箇所はどこかを伝えてください。
• 引き継ぎに記録された競合解決ルールを挙げ、それに従うと伝えてください。「公開済みの意思決定記録の番号を優先し、新しく追加するものは番号を後ろに移す」「文字列テーブルとドキュメントのインデックスでは追記時の競合を想定する」といったルールです。前回すでにコストをかけて決めたことです。今回、異なる方法で競合を解決すれば、誰もしていない2つ目の意思決定になってしまいます。
• マージの方向を提案してください。長期運用ブランチでは、通常 <main> をブランチに取り込み、そこで検証します。その理由も説明してください。

引き継ぎで最初に行うことが別に指定されている場合（設計前にプロバイダーに事実を確認する、不要なチェックアウトを削除する、質問に回答するなど）は、そちらを確認してください。フェーズ一覧のほうが進捗らしく見えるからといって、そちらへ進んではいけません。

作業範囲を提案する

引き継ぎの「次に行うこと」セクションは作業の順序を示し、ユーザーの指示はその範囲を絞り、または上書きします。両者のすり合わせによって、両方を調整します。実行するスキルと同様に、最終ドキュメントの見出しを基準に ID を照合し、柔軟に扱い、コミット済みの項目は除外して解決してください。さらに、引き継ぎによる次の3つのルールを適用します。

• ブロック中の項目は、すり合わせによってブロッカーが解消されたと確認できるまでブロック中のままです。 引き継ぎで理由を示して延期されたフェーズについて、「回答が不要な部分だけ」を始めてはいけません。それではフェーズを二度作ることになります。
• 意図的に未実施の項目は、未実施のままにします。 引き継ぎでは、作業を拡張するのではなく修正してしまわないよう、意図的に残した抜けが明示されています。それでも埋めてしまえば、ユーザーが不在のままプロダクトに関する意思決定をすることになります。
• 優先度を下げた項目は、確認が必要です。 「マイルストーン P — 確認せずに着手しない」は、どれだけ手が空いていても作業範囲に含まれません。

実装する順番で作業範囲をリストにし、最初のインクリメントの内容と、その検証方法を伝えてください。

質問して、返答を待つ

ここでいったん止まり、提案をユーザーに提示してください。 これはインテーク全体が目指していたチェックポイントであり、ツリーを変更する最初のコマンドを実行する前に行います。引き継ぎの略記は使わず、分かりやすい文章で次の内容を伝えてください。

1. 引き継ぎの主張とツリーの状態 — すり合わせの表を示し、矛盾点と、それぞれについてどう対応するかをすべて記載します。
2. 実行するマージ — 取り込まれる内容、競合が予想される箇所、適用する記録済みのルール、マージの方向を説明します。マージの許可を求めてください。
3. その後に進める作業 — 解決済みの作業範囲をリストにし、最初のインクリメントと、どの実行スキルに従って作業するかを示します。これでよいか確認してください。
4. 確認が必要なこと — 最初のインクリメントを妨げる未解決の質問、コードが裏付けていないのに引き継ぎでは完了とされているフェーズ、どちらとも確認できなかったブロッカーなどです。

その後、待ってください。ユーザーからの確認、作業範囲の修正、新しい指示は、それぞれここから先の別のセッションになります。引き継ぎの指示だけを根拠にマージしてはいけません。また、「考えている間に」実装を始めてはいけません。引き継ぎは質問するセッションを想定して書かれており、誰もプッシュしていないブランチに対する、依頼されていないマージは最も大きなコストを伴うミスです。呼び出し時にユーザーが「寝ている間に続けて」と言っていた場合、その指示で許可されるのはこの回答の後に実行することです。この確認に代わるものではありません。それでも質問し、返答を待っていると伝えてください。

すり合わせの結果、対応すべきことが何もない場合は、作業を提案するのではなく、その旨を伝え、close-plan または close-roadmap を案内してください。

マージしてから、実行するスキルに引き継ぐ

ユーザーの確認が取れたら、次のようにします。

• HANDOFF.md を削除します。 これはまさにこの時のために書かれたもので、すでに役目を果たしています。その主張は照合され、落とし穴は作業ルールに取り込まれ、順序は確認済みのスコープになっています。ツリーに残しておくと、次の読者が最も信頼する文書になってしまいますが、方針が変わった時点で内容は正しくなくなっています。git rm で単独の小さなコミットにするか、マージと一緒に削除してください。このセッションで作業を残して中断する場合は、最後に新しい引き継ぎ文書を書きます。前のセッションのツリーではなく、このセッションのツリーをもとにしてください。
• merge-branch のゲートを通してマージします。 機械的に進めず、<main> → ブランチの順で、挙げたルールに沿って解決し、そこで検証します。2つのテキストではなく、2つの動作のどちらかを選んだ解決については、質問ログに記録してください。
• 何かを作り始める前に、マージ後のツリーでテストスイートを1回実行します。 こうすることで、その後に見つかった失敗はすべて、自分の変更か既存の問題の一覧にあるものとなり、マージに起因するものではなくなります。
• マージによってスコープが変わった場合 — フェーズが<main>に取り込まれた変更と競合するようになった、ブロッカーが解消または発生したなど — は、作業を始める前に簡潔に伝えます。小さな調整は報告し、作業計画が変わる場合は改めて確認を求めてください。

ここから切り替えます。PLAN.final.md がある場合は execute-plan に、ROADMAP.final.md がある場合は execute-roadmap に引き継ぎます。引き継ぎ文書に「このロードマップの進め方」というセクションがある場合は、それが実行するスキルの契約を、実際に実行した人が書き直したものです。それに従ってください。次の点を作業に引き継ぎます。

• 落とし穴は恒常的な指示になります。 引き継ぎ文書に記載された落とし穴はすべて、自分の作業ルールと、起動する各サブエージェントへの依頼内容に含めてください。ビルド出力がロックされること、あるプラットフォームで失敗するクリーンアップの手順、作業ディレクトリが維持されるシェル、コミットせずに完了を報告するエージェントなどです。落とし穴を一度伝えておけば、サブエージェントもそれを経験せずに済みます。
• 質問ログにある決定事項は確定済みです。 理由を覚えていないからといって、決定し直してはいけません。ログには採用されなかった選択肢も記録されています。誤って覆すのではなく、必要ならユーザーと意図的に再検討できます。
• ユーザー不在時に決めた引き継ぎ内容は、そのような決定として記録したままにします。今見て誤りだと思われる場合は、黙って覆すのではなく、質問ログに新たな質問として記録します。
• 議論におけるモデルまたは作業量の指示は、実行するスキルの定めに従って適用します。

ここからは実行するスキルが作業を担います。スコープが完了するまで、またはブロックされていない作業をすべて終えるまで、検証済みの変更を1つずつ進め、変更ごとに1つのコミットを作成し、作業を止めずに質問を記録します。

完了処理

実行中のスキルに定められた完了処理を適用します — EXECUTION.md、 ACCEPTANCE.md、クリーンなツリー、平易な言葉での報告です。このスキルでは、 引き継ぎ自体も追加します。

• 未対応の事項が残っている場合は、新しい HANDOFF.md を作成します。 write-handoff に従ってください。 以前のファイルは方針が合意された際に削除されているため、このファイルには 今回のセッションのツリーについて記述します。日付を記載し、冒頭の行で 今回のセッションの範囲を明示し、現在も当てはまる落とし穴だけを引き継ぎます — 再発しない競合に関する落とし穴は、次の読者にとってノイズです — そして 自分が遭遇した落とし穴を加えます。以前のページが非公開の記憶から引用した 事実は、本文に明記してください。
• 範囲が完了している場合は、何も作成しません。 完了した作業に対する引き継ぎは、 その内容が正しくなくなった後も信じられてしまう、実行内容の4つ目の要約です。 完了した作業については EXECUTION.md に記載し、 close-plan または close-roadmap でフォルダーを整理します。
• ユーザーへの報告では、 引き継ぎの記述とツリーの内容が食い違っていた点、 それぞれにどう対処したかを1段落で伝えます — これが、前回のセッションからは 予測できなかった今回のセッションの内容です。続いて、何を構築したかを プロダクトの言葉で説明し、ACCEPTANCE.md を参照し、ユーザーの判断を 待っている質問を伝えます。