ハンドオフ
ハンドオフはスナップショットを出力します。これは、次回セッションが最初に読む固定形式のサマリーです。スナップショット自体はファイル化しません。なぜなら、スナップショットはデフォルトブランチ、マージされたPR、リリースノートから再生成可能であり、それを単に繰り返すだけの常設Issueはノイズになるからです。Issueは、誰かが実際に行う作業に対してのみ作成します。各次サイクル項目は、既存のIssueと照合した上で、該当するものがなければ新規にIssueを作成します。意図的に先送りされた決定は、その決定が既に存在する場所(CHANGELOG、決定記録、該当箇所のコードコメント)に理由を記録します。なぜなら、その理由こそが次回セッションが自力で再構築できない唯一の情報だからです。
ハーネスは既に --continue または --resume でセッションの全履歴を再開でき、またマシンローカルの自動メモリも保持しているため、スナップショットにはそれらでは得られないもの(別のマシンや人がリポジトリやIssueで探す必要のある次のステップや決定)のみを含めます。ゲート判定結果やカウントテーブルは意図的に含めません。これらは記録されたSHAに対して数秒で再実行でき、またコピーされた数値は捏造可能ですが、再実行結果は捏造できないからです。
このスキルはIssueを開いたり閉じたりするため、自動では実行されません。依頼があった場合、そしてセッションが実際に終了する時点でのみ実行してください。
デフォルトのパス
- ツリー状態を収集する:SHA、クリーン状態、ワークツリー、オープンPR。
- 最後のリリースタグ以降(タグがない場合はセッション開始以降)にshippedされたものをリストアップする。
- 主要な発見を1つ、その根拠と共に記述する。
- 次サイクルリストを作成する:順序付けられ、具体的で、各項目に理由を付ける。
- 次サイクルの各項目について、既存のオープンIssueでカバーされているかを確認し、ない場合のみ新規Issueを開き、その番号を記録する。
- 意図的に先送りされたものについては、その決定が既に存在する場所(CHANGELOG、決定記録、該当箇所のコードコメント)に理由を記録する。そのような場所が存在しない場合のみ、'not planned'としてクローズされたIssueを発行する。単に未完了のものに対しては絶対に行わない。それらは次サイクル項目に残るか、黙って削除される。
- レガシークリーンアップ:「Session carryover」というタイトルのオープンIssueが存在する場合、その内容が分割された先のIssue番号を指し示すコメントを付けてクローズする。
- スナップショットを返信に出力する:古さに関する免責事項、ツリー状態、shipped、主要な発見、次サイクルリスト(Issue番号付き)、および先送りされた決定項目(記録場所付き)。
ツリー状態を収集する
レポジトリのデフォルトブランチに対して、セッションが現在いるブランチではなく、以下を実行します。
git rev-parse HEAD
git status --short
git worktree list
gh pr list --state open
正確なSHA、ツリーがクリーンかどうか、ワークツリーの数、オープンPRの数を記録します。「全体的に良い状態」といった曖昧な表現はツリー状態ではありません。SHAは、次回セッションがその下で何も動いていないことを確認できる事実であり、すべてのゲートとカウントが再実行される基準です。だからこそ、それらの結果はどこにもファイル化されません。
何がshippedされたかをリストアップする
最後のリリースタグ(ない場合はセッション開始時点)から現在のHEADまでにマージされたすべてのPRを、番号と内容を1行ずつリストアップします。何もマージされていない場合は、この見出しの下に「なし」と記述します。リストが空だからといって見出しを省略しないでください。セクションがないと「誰も確認していない」と読まれ、「何もshippedされていない」とは読まれません。
主要な発見を記述する
1つの発見を、その背後にある根拠と共に決定として記述します。起こったことすべての要約ではありません。今回のセッションでその基準に達するものがなかった場合は、「今回のセッションでは主要な発見はありません」と書き、小さな観察結果をでっち上げて枠を埋めないでください。
次サイクルリストを作成し、各項目をIssueにする
具体的な次のアクションの順序付きリスト。各項目にはそれを動機付ける1行の理由を添えます。「ここから始める」とは、最初の項目が次回セッションが実際に開始すべき場所であることを意味し、単に最初に思いついたものではありません。
各項目について、新規Issueを開く前に既存のオープンIssueを検索します。
gh issue list --search "<項目の要約>" --state open
既存のオープンIssueがすでにカバーしている場合は、そのIssue番号を使用します。それ以外の場合は、新しいIssueを開きます。
gh issue create --title "<項目>" --body "<1行の理由>"
Issueは、誰かが行う作業のために存在します。Issueにならない次サイクル項目は、単なる散文のリストであり、次回セッションがそれを信頼するしかなく、アクション可能なトラッカーではありません。
先送りされた決定を決定の存在場所に記録する
今回のセッションが意図的に行わないと選択したものは、単に今回のセッションに回ってこなかったものとは異なります。最初の種類のものだけが、その理由と共に、決定が既に存在する場所(CHANGELOGエントリ、決定記録、該当箇所のコードコメント)に記録されます。スナップショット内でその場所を指し示します。そのような場所が存在する場合のみ、次のようにクローズされたIssueとして発行します。
gh issue create --title "<項目>" --body "Deferred by decision: <理由>"
gh issue close <N> --reason "not planned"
理由は、次回セッションが自力で再構築できない唯一の情報です。単に未完了のものは記録する必要はありません。なぜなら、それは依然として次サイクル項目であるか、そもそもコミットされていなかったかのどちらかだからです。
レガシー:既存のキャリーオーバーIssueをクローズする
このプラクティスに変更される前から「Session carryover」というタイトルのIssueがまだオープンになっている場合は、それを永久にオープンのままにせずにクローズします。
gh issue list --search "Session carryover" --state open
gh issue close <N> --comment "Retired: split into <このハンドオフからのIssue番号>."
そのようなIssueが残っていなければ、このステップはスキップします。
スナップショットを出力する
古さに関する免責事項で始めます。文言の精神は正確に:「ここにあるものはすべて使用前に検証してください。これはスナップショットであり、リポジトリは動いています。」次に、順番に:ツリー状態、shipped PR、主要な発見、各項目のIssue番号付きの次サイクルリスト、各項目の記録場所付きの先送りされた決定項目。これを返信に出力します。ファイル化されることはありません。
緊急脱出ハッチ
ghCLIがない、または認証されていない。 スナップショットと次サイクル項目、先送りされた決定項目を出力し、Issueを開けなかったことを明記し、手動で発行してもらう。- shippedなし、主要な発見なし、次サイクル項目なし、先送りされた決定なし。 そのセクションにその旨を明確に記述し、省略したり水増ししたりしない。
禁止事項
- 単独で実行しないでください。Issueを開いたり閉じたりするため、リクエストがあった場合のみ実行します。
- ゲート判定結果やカウントテーブルをスナップショットにコピーしないでください。これらは記録されたSHAから再実行され、読者はコピーではなく再実行結果を信頼します。
- 既存のIssueを確認せずに次サイクル項目のIssueを開かないでください。
- 単に未完了のものに対してIssueを開かないでください。それは先送りされた決定とは異なります。
- セッションが最新だと感じても、古さに関する免責事項を省略しないでください。次に読む人は、それが明示されていなければ知る方法がありません。
- 主要な発見がない、またはshippedリストが空の場合に、スナップショットを実体以上に見せかけるために水増ししないでください。
- このハンドオフが実行された後は、「Session carryover」Issueをオープンのままにしないでください。