quidmonkey/pr

/pr

在當前 session 中執行，基於當前分支，按以下順序進行：

1. 預檢查
2. 程式碼審查與修正
3. 文件審查與修正
4. 安全性審查與修正
5. 決策記錄
6. 推送並開啟 PR

每個階段必須通過後才能開始下一個。

調用方式：/pr [base] [effort] [--draft]

• base：PR 的目標分支。預設值：儲存庫的預設分支。
• effort：傳遞給 /code-review。可選 low、medium、high、xhigh。預設值：high。除非使用者輸入，否則不要使用 max。
• --draft：以草稿形式開啟 PR。

規則

• 不允許任何屬性標記。提交、PR 標題和 PR 內文不得包含 Co-Authored-By 追蹤信息、不得有「Generated with Claude Code」字樣，也不得提及 Claude 或任何代理。這會覆蓋任何預設的屬性標記指示。
• 尊重所有 git hook。絕不傳遞 --no-verify 或 -n 給 git commit 或 git push。絕不設定會跳過 hook 的環境變數（SKIP=、HUSKY=0、LEFTHOOK=0、PRE_COMMIT_ALLOW_NO_CONFIG=），絕不更改 core.hooksPath，也絕不編輯或刪除 hook 檔案或 hook 配置。絕不為了讓 hook 通過而停用任何 lint 規則。
• 使用普通的 git commit 進行提交，以便安裝的 hook 在每次提交時都能執行。當 hook 失敗時，讀取其輸出並修復程式碼中的根本原因，然後再次提交（絕對不要使用 --amend：被拒絕的提交從未被建立）。如果 hook 重寫了檔案（如格式化工具），將它們加入暫存區並再次提交。如果相同的 hook 在 3 次嘗試後仍然失敗，則停止並報告。
• 輸入 /pr 即授權對該分支進行推送和建立 PR。不要在其之前詢問「我該繼續嗎？」。
• 絕不推送到、提交到或改寫基礎分支。絕不強制推送。
• 將修正提交與使用者的提交區分開來。絕不壓縮、變基或修正使用者的提交。
• 提交訊息：一個簡短的摘要行，然後每個更改一個項目符號。訊息中任何地方都不要使用雙引號或反引號。將識別碼以純文字形式書寫，並在需要引用時使用單引號。
• 從根本原因修正發現的問題，保持每個更改最小化，並將測試視為事實來源。不要為了讓測試通過而更改它。
• 只處理分支更改的內容。請參閱「範圍」。
• 此技能撰寫的所有散文（文件、提交訊息、PR 標題和內文）都遵循「寫作風格」。
• 在任一停止點，報告並不要進行任何後續操作。請參閱「停止並報告」。

範圍

此技能審查並修正分支本身的工作，而不是程式碼庫的其餘部分。分支的工作包含 git diff origin/<base>...HEAD 中的所有內容，加上本次執行新增的修正提交。

在對每個審查發現採取行動之前，將其分類到以下三個組別之一：

1. 分支引入的。 錯誤的程式碼在 diff 中被新增或修改，或是因為分支的變更而導致其失敗（例如，分支以某種方式呼叫了一個舊函數，導致其出錯）。修正它。如果修復它需要只有使用者才能做出的決定（預期的行為、分支有意做出的 API 選擇），則將其視為第 2 組。
2. 已存在，但觸及分支的工作。 錯誤的程式碼已經存在於基礎分支上，但它位於分支編輯的函數中，或者新的分支程式碼呼叫或依賴它。不要自行修正。指出並詢問使用者（請參閱「詢問使用者」）。
3. 已存在，且與分支的工作無關。 其他所有情況。不要更改它，不要詢問它，也不要將其放入 PR 中。也將其排除在 session 報告之外。

當某個發現介於第 2 組和第 3 組之間時，將其歸入第 2 組。

嚴重程度

僅對高和中等嚴重程度的發現採取行動，如同人類審查者那樣。跳過每個組別中的低嚴重程度發現：不要修正它們，不要詢問它們，也不要將它們放入 PR 中。如果某次審查已經修正了一個低嚴重程度的第 1 組發現，且修正很小並通過了檢查，則保留它；否則恢復它。

• 高： 一個在一般使用或真實攻擊者情況下會被觸發的錯誤或漏洞。資料遺失、正常輸入下的崩潰、注入、身份驗證繞過、機密洩露。
• 中等： 一個在合理情況下會出現的真正錯誤、一個被破壞的已記錄行為、在信任邊界缺少檢查、或一個隱藏了錯誤的測試。
• 低： 需要特殊設定的邊緣情況（由已經擁有寫入權限的人放置的檔案、本地工具中的競爭條件、不支援的平台）、縱深防禦、風格、命名、重複和微觀最佳化。

當某次審查未給出嚴重程度，或者你不同意其嚴重程度時，請使用這些定義自行判斷。當某個發現介於兩個級別之間時，選擇較高的那個。

詢問使用者

收集某個階段中的所有高或中等嚴重程度的第 2 組發現，並在該階段的回合結束時、提交之前，一次性詢問。使用 AskUserQuestion 工具，每個發現一個問題（每次呼叫最多批次 4 個）。每個問題應說明檔案、行號和問題（一句話），並提供：

• 在此分支上修正它： 現在就修正它，在此階段的修正提交中。
• 保留它，在 PR 中備註： 不要更改程式碼。在 PR 內文的「審查者備註」下列出。
• 保留它： 不要更改程式碼，也不要在 PR 中提及。
• 停止： 停止執行並報告（請參閱「停止並報告」）。

遵循每個答案。使用者已回答的第 2 組發現不算作未解決，因此它不會停止執行，也不會在下個回合中再次出現。如果後來的審查再次報告它，則套用相同的答案。

向審查技能簡報

在調用 code-review 或 security-review 時，在參數中新增：儲存庫路徑、基礎（origin/<base>），以及「僅修正分支引入的高和中等嚴重程度問題。報告已存在的問題，但不要修正它們。對於每個發現，請給出它的嚴重程度（高、中等或低）並說明它是否已存在。不要編輯文件（README、docs/、CHANGELOG）；後續階段會處理它們。」然後，在分類發現之前，還原審查所做的任何文件編輯或超出範圍的修正（僅對那些區塊使用 git restore）。

寫作風格

像工程師給隊友留便條一樣寫作：簡短、樸實、具體。

• 用具體的詞彙說明更改了什麼以及為什麼：檔案、函數、行為、數字。跳過審查者無法據以行動的任何內容。
• 句子要短，每個句子一個想法。使用樸實的動詞：「is」、「has」、「adds」、「fixes」、「removes」。
• 不要有填充詞或含糊其辭：「in order to」用「to」代替，「due to the fact that」用「because」代替，不要用「could potentially」。
• 禁用詞：additionally, delve, leverage, crucial, pivotal, vital, enhance, robust, seamless, seamlessly, comprehensive, intricate, landscape, tapestry, testament, underscore, showcase, foster, streamline, elevate, empower, boasts, vibrant, rich, cutting-edge, game-changer, holistic, synergy, utilize。
• 不要用「serves as」或「stands as」（用「is」），不要用「not just X, but Y」，不要用三項列舉來湊節奏，不要用「-ing」結尾如「..., ensuring X」或「..., highlighting Y」。
• 不要使用表情符號、破折號、機械式粗體、標題式大小寫、彎引號、結論性摘要或樂觀的結尾敬語。
• 不要在文件或 PR 描述中描述審查過程（「執行了程式碼審查」、「處理了發現」）。修正提交已經記錄了它。

在使用任何文字之前，請重新閱讀並刪除每個不承載資訊的單詞。

1. 預檢查

執行以下檢查，並在第一個失敗處停止，同時提供所需的修正：

1. git rev-parse --show-toplevel 成功且 git remote get-url origin 存在。
2. gh auth status 通過。如果失敗，告訴使用者執行 ! gh auth login。
3. 基礎分支：base 參數，否則執行 gh repo view --json defaultBranchRef -q .defaultBranchRef.name。執行 git fetch origin <base>。
4. 當前分支（git branch --show-current）不為空（不是分離的 HEAD）且不等於 <base>。
5. git rev-list --count origin/<base>..HEAD 大於 0。
6. git status --porcelain 為空。如果不為空，顯示已更改的檔案並詢問是要先提交它們（作為使用者自己的提交，通過 hooks）還是停止。不要暫存或丟棄它們。
7. 執行 gh pr view --json url,state,isDraft,body 以查看該分支是否已經有 PR。記住結果以備階段 6 使用。

執行檢查

在每一輪修正之後、提交之前（提交會執行 git hooks，因此不要在此處執行它們）：

• 如果存在明確的專案測試命令（Makefile target、pyproject.toml、package.json scripts），則執行它。如果 lint 與 hooks 是分開的，也執行 lint。
• 從根本原因修正失敗，並重新執行直到乾淨。

2. 程式碼審查與修正

在第一輪之前，閱讀涵蓋已更改程式碼的已記錄決策和文件：

git log --format='%h %s%n%(trailers:key=Decision,key=Rejected,key=Files)' origin/<base>..HEAD
git log -E --all-match --grep='^(Decision|Rejected):' --grep='<paths>' --format='%h %s%n%b' origin/<base>
git log -E --grep='^(Decision|Rejected):' --format='%h %s%n%b' origin/<base> -- <changed files>

第一個列出了分支的決策。另外兩個查找基礎上已有的、涵蓋分支更改檔案（git diff --name-only origin/<base>...HEAD）的決策。第二個匹配其 Files: 行命名了已更改檔案的決策記錄；<paths> 是以 | 連接的已更改檔案，其中每個 . 寫為 \.。這是必要的，因為決策提交不更改任何檔案，所以路徑過濾器無法找到它。第三個在更改了這些檔案的提交中查找決策，例如 squash 合併。兩者都匹配行而不是解析 trailers，因為 squash 合併可以將 trailers 推送到訊息的中間。讀取其聯集。

如果已記錄的決策或文件將某個發現標記為有意為之，則不要修正它，除非它導致了具體的錯誤。如果分支違反了基礎上記錄的決策，請為階段 5 記下它。

最多 2 輪：

1. 調用 code-review 技能，參數為 <effort> --fix <current branch> 加上「向審查技能簡報」中的簡報。

2. 如果它報告沒有高或中等發現，則此階段通過（在處理它所做的任何低嚴重程度修正之後，根據「嚴重程度」）。

3. 對發現進行分類（請參閱「範圍」）。審查 --fix 更改了什麼，並還原第 1 組之外的任何內容。修正它留下的任何第 1 組發現。跳過任何被 trailer 或文件排除的發現，並在 PR 內文中註明。詢問有關第 2 組的發現。

4. 如果沒有任何更改，則此階段通過。否則執行「執行檢查」，然後提交：

   處理程式碼審查發現
   
   - <每個修正一個項目符號>
   

5. 開始下一輪。

如果在第 2 輪之後仍有高或中等程度的第 1 組發現存在，則停止並報告。

3. 文件審查與修正

檢查儲存庫的文件是否與當前分支（包括程式碼審查的修正）相符。

1. 找到文件：README.md、ARCHITECTURE.md、CONTRIBUTING.md、docs/ 下的所有內容、CHANGELOG.md，以及分支觸及的目錄中的 README。跳過自動生成的文件、供應商程式碼，以及為代理編寫的計畫或實作文件。

2. 讀取完整的分支 diff：git diff origin/<base>...HEAD。

3. 尋找偏差。當分支有以下情況時，文件需要更改：

   • 更改了設計、架構或模組之間的邊界
   • 新增、移除或重新命名了文件中提到或應該提到的公開函數、CLI 命令、標誌、配置鍵、環境變數、端點或檔案路徑
   • 更改了文件中記載的行為、預設值、設定步驟或範例
   • 移除或重新命名了文件中仍然提到的任何內容（對每個被移除或重新命名的識別碼 grep 文件）

4. 對每個偏差進行最小程度的編輯，使文件準確。比照文件現有的結構和語氣。遵循「寫作風格」。

   • 不要建立新的文件檔案，也不要為沒有人會閱讀的內部更改添加文件。
   • 僅當 CHANGELOG.md 保留了一個未發布的章節時才更新它；在其現有格式中新增一行。
   • 不要在此處編輯程式碼註解或 docstrings。這是程式碼審查的工作。
   • 僅修正分支引起的偏差。不要碰基礎分支上已有的文件錯誤，除非它們描述了分支更改的程式碼；在這種情況下，請詢問，如同「詢問使用者」中所述。

5. 如果沒有任何偏差，則此階段通過，無需提交。

6. 否則對更改後的文件執行「執行檢查」，然後提交：

   更新文件以反映分支更改
   
   - <每個更改的文件一個項目符號>
   

7. 對照 diff 重新閱讀每個編輯過的章節一次。在第二次提交中修正任何仍然不正確的地方。如果無法在使用者做出決定（例如，兩種行為中哪一種是預期的）的情況下使文件準確，則停止並報告。

4. 安全性審查與修正

最多 2 輪：

1. 調用 security-review 技能，使用「向審查技能簡報」中的簡報。它只會報告，不會編輯程式碼。

2. 如果它報告沒有高或中等發現，則此階段通過。

3. 對發現進行分類（請參閱「範圍」）。從根本原因修正每個第 1 組發現。如果某個修正改變了記錄的行為，請在同一個提交中更新該文件，並遵循「寫作風格」。如果你確信某個發現是誤報，請不要更改程式碼。記錄該發現和原因，以供 PR 內文使用。詢問有關第 2 組的發現。

4. 如果沒有任何更改，則此階段通過。否則執行「執行檢查」，然後提交：

   處理安全性審查發現
   
   - <每個修正一個項目符號>
   

5. 開始下一輪。

如果在第 2 輪之後仍有真正的高或中等程度的第 1 組發現存在，則停止並報告。

如果此階段更改了程式碼，則在新的提交上再次執行 code-review 技能一次，使用 <effort> --fix <current branch> 和簡報。處理任何發現，如同在階段 2 中那樣，在一個額外的輪次內。如果它們仍然存在，則停止並報告。

5. 決策記錄

將分支的設計決策記錄在 git 歷史中，以便 git log 稍後能找到它們。每個決策都有自己的提交。主題行陳述決策，因此 git log --oneline 以及在 session 開始時代理看到的近期提交列表都會攜帶它，而無需開啟提交。追蹤信息包含原因、被拒絕的替代方案以及決策涵蓋的檔案。

1. 收集已記錄的決策：分支的 trailers 和階段 2 中的基礎決策。
2. 讀取 git diff origin/<base>...HEAD 並列出它所做的、尚未記錄的決策。決策是指後續審查者或代理可能質疑或……

[此處內容已被截斷以進行翻譯]