交接
交接會列印一份快照:下一個工作階段首先看到的固定形狀摘要。它不會為快照本身建檔,因為快照可從預設分支、已合併的 PR 和發行說明中重新推導,而且一個僅重複陳述該資訊的常設 Issue 只會製造噪音。它只會為有人將要做的工作開啟 Issue:每個下一個循環的項目都會變成一個 Issue,並先與已開啟的 Issue 進行比對。任何因決策而延遲的事項,其理由會被記錄在決策原本就存在的地方,因為該理由是下一個工作階段無法自行重建的唯一事物。
框架已經能透過 --continue 或 --resume 恢復工作階段的完整歷史,並保留機器本機的自動記憶,因此快照只攜帶那些它們無法提供的東西:另一台機器或其他人需要在儲存庫或其 Issue 中找到的下一步行動和決策。閘門判定和計數表格刻意不包含在內:兩者都能在幾秒鐘內依據記錄的 SHA 重新執行,而且重新執行的數字不像拷貝的數字那樣可以偽造。
此技能可以開啟和關閉 Issue,因此它絕不會自行觸發。只在被要求時執行,且僅在工作階段確實結束時執行。
預設路徑
- 收集樹狀狀態:SHA、乾淨度、工作目錄樹、已開啟的 PR。
- 列出自上次發行標籤以來(如果沒有標籤,則從工作階段開始)已出貨的內容。
- 說明一個重點發現,並附上證據。
- 撰寫下一個循環清單:有序、具體,每個項目附帶其理由。
- 對於每個下一個循環的項目,檢查已開啟的 Issue 是否已涵蓋該項目;僅在沒有 Issue 涵蓋時才開啟新 Issue,並記錄其編號。
- 對於任何因決策而延遲的事項,將理由記錄在決策原本就存在的地方(CHANGELOG、決策記錄、該處的程式碼註解);僅在沒有此類場所存在時,才將 Issue 歸檔為「不計劃」並關閉。切勿對單純未完成的事項執行此操作;該事項會保留為下一個循環的項目或靜默移除。
- 舊版清理:如果存在標題為「Session carryover」的已開啟 Issue,則關閉它,並附上指向其內容被拆分到的 Issue 的評論。
- 在回覆中列印快照:過時免責聲明、樹狀狀態、已出貨內容、重點發現、帶有 Issue 編號的下一個循環清單,以及每個延遲決策事項的記錄位置。
收集樹狀狀態
針對儲存庫的預設分支執行這些指令,而不是工作階段當前所在的分支:
git rev-parse HEAD
git status --short
git worktree list
gh pr list --state open
記錄確切的 SHA、樹狀是否乾淨、工作目錄樹的數量以及已開啟的 PR 數量。模糊的「狀態良好」不是樹狀狀態;SHA 是讓下一個工作階段確認沒有任何東西在它底下移動的事實,也是每個閘門和計數重新執行的依據,這就是為什麼這些結果都不會被歸檔到任何地方的原因。
列出已出貨內容
從上一個發行標籤(如果沒有,則從工作階段開始)到當前的 HEAD,列出每個已合併的 PR,每行一個:編號及其作用。如果沒有合併任何 PR,在此標題下寫「無」。如果清單為空,請不要省略標題;缺少區塊會被解讀為「沒人檢查」,而不是「沒有出貨」。
說明重點發現
一個發現,以決策的形式陳述,並附上支持它的證據,而不是對所有發生事情的摘要。如果本次工作階段沒有任何事項達到該標準,請寫「本次工作階段沒有重點發現」,而不是誇大一個小觀察來填補這個位置。
撰寫下一個循環清單,並將每個項目變成 Issue
一個有序的具體下一步行動清單,每個項目附帶一行說明其動機的理由。「從這裡開始」意味著第一個項目確實是下一個工作階段應該開始的地方,而不僅僅是想到的第一件事。
對於每個項目,在開啟新 Issue 之前先搜尋已開啟的 Issue:
gh issue list --search "<項目摘要>" --state open
如果一個已開啟的 Issue 已經涵蓋該項目,則使用該 Issue 的編號。否則開啟一個新的 Issue:
gh issue create --title "<項目>" --body "<一行理由>"
Issue 存在於某人將要做的工作;一個從未變成 Issue 的下一個循環項目只是一個散文清單,下一個工作階段必須信任它,而不是一個它可以據以行動的追蹤器。
將因決策而延遲的事項記錄在決策所在之處
本次工作階段刻意選擇不做的事,與單純未輪到本次工作階段的事不同。只有第一種需要被記錄,連同其理由,記錄在決策原本就存在的地方:圍繞它發貨的 CHANGELOG 條目、決策記錄,或該處的程式碼註解。在快照中指出該位置。僅在沒有此類場所存在時,才將其歸檔為已開啟並關閉的 Issue:
gh issue create --title "<項目>" --body "因決策延遲: <理由>"
gh issue close <N> --reason "not planned"
理由是下一個工作階段無法自行重建的唯一一行;單純未完成的事項不需要記錄,因為它要么仍然是下一個循環的項目,要么從來就不是一個承諾。
舊版:收回一個已開啟的延續 Issue
如果一個標題為「Session carryover」的 Issue 在此做法改變之前仍然開啟,則將其關閉,而不是讓它永遠保持開啟:
gh issue list --search "Session carryover" --state open
gh issue close <N> --comment "已收回:拆分為 <本次交接的 Issue 編號>。"
一旦沒有此類 Issue 存在,則跳過此步驟。
列印快照
以過時免責聲明開頭,精神上逐字照錄:「在此依賴任何內容之前請先驗證,這是快照,儲存庫會變動。」然後按順序:樹狀狀態、已出貨的 PR、重點發現、帶有每個項目 Issue 編號的下一個循環清單、每個延遲決策事項及其記錄位置。在回覆中列印此內容;它永遠不會被歸檔。
逃生門
- 沒有
ghCLI,或未經認證。 仍然列印快照以及下一個循環和延遲決策的項目,說明無法開啟 Issue,並讓人手動歸檔它們。 - 沒有已出貨的內容、沒有重點發現、沒有下一個循環的項目、或沒有因決策而延遲的事項。 在該區塊中如實說明,而不是將其省略或填充內容。
禁止事項
- 不要自行執行此技能。它可以開啟和關閉 Issue,且僅在要求時觸發。
- 不要將閘門判定或計數表格複製到快照中;它們會從記錄的 SHA 重新執行,讀取者相信重新執行的結果,而不是拷貝。
- 不要在不檢查是否有已涵蓋該項目的 Issue 的情況下,為下一個循環的項目開啟 Issue。
- 不要為單純未完成的事項開啟 Issue;這與因決策而延遲不同。
- 不要因為工作階段感覺很新就跳過過時免責聲明;如果沒有明確陳述,下一個讀取者無法知道這一點。
- 不要為了讓快照看起來比工作階段實際更豐富而填充缺少的重點發現或空的已出貨清單。
- 一旦此交接執行完畢,不要讓「Session carryover」Issue 保持開啟狀態。