PR 描述撰寫器
讀取當前分支的差異，並撰寫完整的 GitHub Pull Request 描述。使用一個指令即可建立或更新 PR。
寫作風格
所有產生的 PR 描述均套用以下規則：
- 使用主動語態。例如「新增快取層」而非「快取層已被新增」。
- 摘要使用現在式（「新增快取層」），背景說明使用過去式（「舊方法在每次渲染時造成 N 個請求」）
- 使用簡短句子，一個想法一個項目符號
- 不使用長破折號 — 請改用逗號或句號
- 不使用贅詞：「此 PR」、「此提交」、「根據討論」
- 具體勝過概括：「將 p95 延遲從 800ms 降低至 90ms」優於「改善效能」
步驟 1：檢查設定
確認 gh 已通過驗證：
gh auth status
如果未驗證：gh auth login 並依照提示操作。
確認當前目錄是 Git 儲存庫且有活動分支：
git branch --show-current
如果處於分離 HEAD 或沒有分支，請停止並詢問使用者想要描述哪個分支。
步驟 2：收集差異上下文
執行以下三個指令以建立上下文：
檔案摘要（變更了什麼）：
git diff main...HEAD --stat
提交訊息（為什麼變更）：
git log main...HEAD --oneline
完整差異（如何變更）：
優先使用 origin/main（始終為最新），若無則使用本地 main，再來是 master：
if git rev-parse origin/main &>/dev/null 2>&1; then
BASE=origin/main
elif git rev-parse main &>/dev/null 2>&1; then
BASE=main
else
BASE=master
fi
git diff $BASE...HEAD
如果差異非常大（超過 500 行），僅讀取 --stat 摘要與提交訊息。同時讀取差異的前 200 行，以瞭解主要變更，而不處理整個輸出。
同時檢查是否有現有的 PR，並讀取其當前標題/內容：
gh pr view --json title,body,baseRefName 2>/dev/null
步驟 3：閱讀格式指南
在撰寫任何內容之前，完整閱讀 references/pr-format-guide.md。內化：
- 必要的章節及其順序
- 如何撰寫每個章節
- 應包含與應省略的內容
- 測試章節的格式
步驟 4：產生描述
使用 references/pr-format-guide.md 中的格式撰寫 PR 描述。
規則：
- 變更章節中的每個項目符號都必須對應到差異中的某處
- 不要憑空發明未由程式碼變更暗示的測試步驟
- 如果某個章節沒有相關內容，則完全省略（不要寫「無」或留空）
- 螢幕截圖章節：僅當差異中顯示有 UI 變更時才包含
- 如果提交訊息解釋了「為什麼」，請在摘要中使用該上下文
品質檢查點： 在呈現之前，請驗證：
- 摘要為 1-2 句，主動語態，無贅詞
- 每個變更項目符號都具體且對應到差異
- 沒有憑空發明的指標或結果
- 測試步驟是可操作的（他人可以遵循）
- 任何一行都沒有使用長破折號
步驟 5：建立或更新 PR
向使用者呈現描述，並詢問：「準備好建立 PR、更新現有 PR，還是僅輸出？」
建立新的 PR：
透過標準輸入傳遞內容，以安全處理反引號、引號和換行：
gh pr create --title "TITLE_HERE" --body-file - << 'EOF'
BODY_HERE
EOF
根據提交訊息和差異摘要建議一個標題。標題應使用祈使語氣，且長度不超過 72 個字元：「為使用者 session 查詢新增 Redis 快取」而非「已新增快取」
更新現有的 PR：
gh pr edit --body-file - << 'EOF'
BODY_HERE
EOF
僅輸出： 在程式碼區塊中呈現標題和內容，供手動複製貼上。
建立或更新後，確認：「PR 描述已更新。請在以下網址檢視：[URL]」