steve-swanson/review-work

審查工作

此技能負責審查程式碼，在本地網頁上顯示結果，並僅修復使用者批准的項目。所有批准的修復會集中在一個分支上，並透過一個 Pull Request (PR) 提交。

主要代理（執行此技能的聊天程式）負責主導工作。它設定範圍、為每個輔助代理選擇模型、儲存所有記錄，並檢查所有結果。輔助代理則負責執行分配給它們的工作並回報結果。

此技能與 plan-work 和 execute-work 搭配使用，但不會呼叫或修改它們。

本文用語

• 被審查分支：正在接受審查的分支。PR 會合併回這個分支。它不一定是 develop。
• 被審查提交：被審查的確切提交 SHA。每個發現都會指向它。
• 發現：審查中發現的一個問題或疑問，具有像 R001 這樣的 ID。
• 頁面：本地 Web 頁面，使用者在其中為每個發現選擇修復、不修復或說明。
• 批次：一次點擊提交所傳送的一系列選擇。
• 工作目錄：同一個儲存庫在自己資料夾中的額外簽出。
• 協調器分支：收集所有修復的單一分支（及其自己的工作目錄）。它將成為 PR。命名應符合 Conventional Branch 風格，<type>/<short-description>，使用小寫字母與連字號。審查修復通常使用 fix/，例如 fix/session-recovery；若所有修復更適合使用 refactor/、perf/、docs/、test/ 或 chore/，則使用之。如果使用者或儲存庫指定了不同的慣例 (例如在 AGENTS.md 中)，則遵循該慣例。切勿在名稱中使用 integration。
• 任務分支：一個短暫的分支和工作目錄，供一個輔助代理進行一個修復。
• 快轉合併：一種僅將分支向前移動且不添加合併提交的合併 (git merge --ff-only)。
• 執行所屬：由此審查執行所建立。清理僅處理屬於此執行的分支和工作目錄。名稱相符並非所有權的證明。

使用者已允許的事項

• 啟動此技能表示允許審查記錄與本地頁面服務。
• 選擇在另一台已連結的機器上顯示頁面，允許在該機器上啟動一個頁面主機執行緒，位於名為 Review-work pages 的 T3 專案中（若不存在則建立）。它僅執行 review-work CLI，絕不會觸碰該處的程式碼。審查完成後，可以依照 remote-page.md 中的說明，清理該執行緒並刪除 Review-work pages 專案（這會刪除其聊天記錄）。切勿刪除任何其他專案。此審查聊天絕不會位於該專案中：它會保留，並接收最終報告。
• 提交修復（在頁面上，或是在聊天中明確表示「修復它」）允許建立任務工作目錄、提交、合併到協調器分支、安全清理、推送，以及建立一個待審查的 PR。也允許監看該 PR 直到它被合併，然後在此審查機器上移除本次執行未修改、已合併的協調器工作目錄和本地分支。
• 如果使用者說「僅限本地」或「不要建立 PR」，則遵循該指示。
• 切勿合併 PR、開啟自動合併或進行部署。

步驟 1：確定審查範圍

1. 讀取儲存庫的說明、需求、狀態、分支和工作目錄。不影響未提交的編輯或其他執行。
2. 記錄儲存庫路徑、共享 Git 資料夾、分支、基礎基底、被審查的提交 SHA、主機（機器名稱）以及聊天 ID。
3. 僅審查已提交的程式碼，使用 git show、差異比對或一個乾淨的受管簽出。未提交的檔案不屬於審查範圍。
4. 選擇範圍：
   • 功能分支：審查其相對於基礎基底的差異。從使用者、專案規則或 PR 元資料取得基礎基底。若仍不清楚，則提問。
   • develop：審查整個當前程式碼。不要自行臆測開始日期或開始提交。
5. 詢問 「使用 inline 還是 subagent fanout？」，除非使用者已指定。
   • Inline：主要代理自行審查。修復仍使用輔助代理。
   • Fanout：輔助代理並行審查。詢問一次最多需要多少輔助代理，並根據有用的獨立區域數量提出建議。提供 自動 選項：在容量允許範圍內啟用最多有用的輔助代理。如果容量未知，則將限制設為 4。其餘的排入佇列。
6. 在建立任何工作目錄之前，先儲存當前工作目錄、本地分支和受管附件的快照。維護此執行所建立的每個工作目錄的清單：包括審查者、修復者、輔助代理、重試及其子項，以及未修改或已放棄的。請參閱 cleanup.md。

步驟 2：啟動審查記錄

• 使用 Node 24+ 和此技能的 scripts/review.mjs。命令詳見 runtime.md。
• 執行一次 init，使用一個保留在專案外部的 JSON 輸入檔案。儲存回傳的審查資料夾路徑並重複使用。恢復時，切勿建立新的執行。
• 記錄位於 <home>/.agents/state/review-work/。執行期會在任何其他檔案之前，先在此目錄中建立其 .gitignore，因此 Git 永遠不會追蹤它們。
• 儲存庫的識別是基於其清理後的遠端 URL 加上其實際的共享 Git 資料夾。同一個克隆的連結工作目錄共享一個識別；不同的克隆則有各自的識別。每個執行也有自己的 ID，因此同時進行的審查不會混淆。
• 只有主要代理及其頁面服務會寫入記錄。切勿將資料庫、服務或狀態複製到工作目錄或 .worktreeinclude 中。輔助代理回傳結果，由主要代理儲存。輔助代理將大型檔案放在自己的暫存資料夾中；主要代理負責匯入它們。

步驟 3：選擇模型，然後進行審查

請先閱讀 routing.md。

• 主要代理為每個審查和修復任務選擇精確的模型和努力程度。它會檢查主機是否提供這些選項，然後在開始任務前記錄選擇。輔助代理永遠不會呼叫 Jev 或選擇路由（模型、努力程度或選項）。它們永遠不會自行啟動其他輔助代理，除非主要代理給它們一個精確、固定的指派。
• 保持在聊天的模型家族內：GPT 聊天使用 GPT 模型；Claude 聊天使用 Claude Opus、Sonnet 或 Haiku。
• 始終使用最新版本。 模型按層級名稱選擇 (Astra、Sol、Terra、Opus、Sonnet、Haiku)。對於每個層級，執行期在主機的模型清單中只保留最新版本，並拒絕舊版本。切勿憑記憶選擇版本。相信主機的模型清單，而非猜測。切勿自行發明模型 ID 或靜默切換供應商。如果家族未知或需要的模型缺失，請詢問。
• Jev 可以先選擇模型，然後選擇該模型支援的努力程度。它需要一個金鑰。透過執行期的憑證發現來找到它，切勿自己開啟檔案。發現流程會先檢查 <home>/.config/jev/credentials.env (TYPESAFE_API_KEY 是建議的名稱)。如果沒有可用的 home 金鑰，則檢查專案實際的環境變數載入順序及其設定的適配器，然後傳遞那些 env 檔案路徑。切勿列印、儲存或 source 金鑰檔案或金鑰值。完整的查詢順序在 routing.md 中。
• 一個已設定的 Jev MCP 適配器可以做出相同的兩個選擇。請先讀取其真實的工具架構；不要假設存在 jev_route 工具。如果沒有適配器，則使用執行期的內建直接傳輸。
• 每個模型的努力程度上限： 審查和規劃最高達到 extra-high，絕不超過 max 或 ultra。修復最高達到 High。執行期會拒絕任何超過上限的路由，無論來自 Jev 或主要代理。
• 如果 Jev 缺失或給出不可用的答案，主要代理將根據相同規則自行決定。沒有固定的備用表。
  • 唯讀列出工作：使用 Low 即可。
  • 演算法或困難推理：使用 High 或 extra-high。
  • 不確定時：使用 High。
  • 安全性審查和規劃（登入、權限、秘密、加密、租戶隔離、信任邊界）：使用最新版 GPT Astra 或最新版 Claude Opus，努力程度為 extra-high。如果該模型沒有 extra-high，則使用相同模型在其上限以下（至少 High）的最高等級。不要切換到較舊版本。如果輔助代理發現新的安全範圍，它會停止該部分並向主要代理報告。 計劃的實作使用以下修復路由，包括安全修復。
  • Inline 審查中，如果部分內容需要更高的路由： 不要要求使用者變更此聊天的模型或努力程度。此聊天無法確認或設定自己的努力程度。將該部分（例如安全檢查）交給一個審查輔助代理，並在啟動它時設定向該輔助代理的精確模型和努力程度（在 Claude Code 中，使用 Agent 工具的 model 和 effort；在 T3 中，使用 delegate_task 選項）。先記錄路由。輔助代理回傳發現；主要代理儲存它們。僅在主機無法以所需模型和努力程度啟動輔助代理時，才詢問使用者：然後說明差距，並提議保留此聊天的模型。為此審查記錄一次該選擇，不再詢問。這絕不會降低 fanout 輔助代理的規則。
• 根據行為和檔案來劃分審查。追蹤跨檔案的流程。尋找程式碼可能出錯的方式：錯誤結果、違反規則、資料遺失、缺少檢查以及相容性問題。對照需求與實際執行的程式碼來檢查每個關注點。合併重複的項目。
• 記錄覆蓋範圍：你已檢查、跳過和無法完成的項目，包含路徑、SHA、理由和證據。「沒有發現」並不表示每個檔案都已檢查。在重要的覆蓋範圍未得到說明（未記錄為已檢查、跳過或未完成）時，不要認為審查已完成。

步驟 4：撰寫易於理解的發現

使用者僅根據發現的文字來決定，因此文字必須簡短、精確且平實。請閱讀 writing-findings.md。將此檔案的路徑傳遞給每個審查輔助代理，並告知其遵循該指引。

使用 Conventional Comments 標籤，例如 issue、question、suggestion 和 nitpick。將每個發現標記為 blocking 或 non-blocking。每個發現包含四個部分：

• 標題： 用 80 個字元以內的平實句子描述問題所在。「重試付款可能產生兩張發票」，而非「非冪等發票建立路徑」。
• 重要性 (discussion)：誰或什麼受到影響，何時以及多頻繁。
• 證據 (evidence，以及可選的程式碼 excerpt)：path:line、程式碼路徑或步驟，以及你如何得知。
• 修復想法 (suggestion)：以「小型修復」、「中型修復」或「大型修復」開頭，然後說明要更改的內容。

如果不確定，請寫成 question。切勿將猜測當作已確認的 issue。為每個發現提供一個穩定的 ID、路徑和行號，以及被審查的 SHA。

在載入發現之前，對每個發現執行 writing-findings.md 中的清晰度檢查。重新撰寫任何未通過的發現，並保留所有事實。

步驟 5：顯示頁面並收集決定

1. 載入發現和覆蓋範圍，然後啟動頁面。一個頁面服務於整個審查，包括後續的回合。

2. 對於每個發現，使用者選擇修復、不修復或說明，並且可以為任何一個添加備註。選擇會儲存為草稿。切換選擇會保留備註。

3. 只有提交會傳送一個批次。部分批次沒問題；未決的發現會保持開啟。已提交的選擇在頁面上會鎖定。變更在聊天中進行。

4. 首先檢查執行環境。 此聊天在 T3 Code 中執行，當其 shell 設定了 T3CODE_THREAD_ID 或 T3CODE_CLI_PATH 變數時，或當 T3 工具如 t3_environment_links 可用時。如果不是：

   • 在此機器上顯示頁面，使用 deliveryMode: "terminal"。
   • 跳過下方的頁面主機選擇，且不提議另一台機器。不要閱讀 remote-page.md。
   • 使用第 5 項中純終端的措辭。

   在 T3 中，根據聊天的起源選擇顯示頁面的位置。 將此選擇與 inline/fanout 選擇分開。

   • 尊重此聊天中已做出的明確頁面主機選擇。恢復時，重複使用它；僅在使用者更改它或該主機無法使用時，才再次詢問。
   • 如果聊天是在審查機器上本地啟動的，則在該機器上顯示頁面，無需詢問。根據使用者的陳述或主機提供的、能識別起始裝置的用戶端來源元資料來確定。代理的主機名稱、工作目錄、執行環境或 creationSource (web、mobile 或 mcp) 單獨並不能證明使用者在哪裡啟動了聊天。
   • 如果聊天是遠端啟動的，或其來源不確定，則詢問一次要在哪裡顯示頁面。直接詢問頁面主機，不要另外詢問使用者是否在本地。呼叫 t3_environment_links 並提議此機器加上每個具有完整存取權限的可達連結機器，使用它們實際的標籤。不要因為作業系統而遺漏任何機器。如果已知功能/存取權限有阻礙，應解釋而非靜默隱藏主機。如果問題工具無法容納所有選擇，請在問題中列出所有合格的主機，並接受主機名稱。
   • 當使用者的機器已知且符合資格時，推薦使用。僅在螢幕鎖定限制影響選擇時解釋此限制：T3 的串流瀏覽器會在審查機器螢幕鎖定時停止。將所選主機和起源證據 (或 unknown) 儲存在審查記錄中。
   • 在另一台機器上： 遵循 remote-page.md。頁面會在使用者自己的瀏覽器中開啟，提交會將選擇傳送回此聊天。它需要完整存取權限的 T3 連結。在此機器鎖定時也能運作。

5. 始終提供主機和頁面連結。

   • 在 T3 內，在本機上： T3 瀏覽器可以開啟頁面。說 「提交會自動恢復此對話。」 頁面使用本地 t3 thread send 命令。不需要公開的 webhook 或通道。
   • 在 T3 內，在另一台機器上： 說明哪台機器顯示頁面，以及 「提交會將您的選擇傳送回此聊天。」
   • 在純終端中： 說：
     1. 開啟審查頁面。
     2. 為每個發現選擇一個選項，如需要可新增備註，然後點擊提交。
     3. 回到此聊天以

…

[因翻譯需求截斷]