pr-writer

PR Writer

將 PR 內容撰寫成給審查者的說明，而非變更記錄、範本、驗證記錄或逐檔摘要。

檢視變更

需要已認證的 gh。檢視目前分支、工作目錄、PR、基底分支、提交記錄及完整差異：

git branch --show-current
git status --porcelain
gh pr view --json number,title,body,url,baseRefName,headRefName
gh repo view --json defaultBranchRef

如果 gh pr view 回報沒有 PR，則繼續進行首次 PR 建立。對於現有 PR，使用其 baseRefName；否則使用儲存庫的預設分支。設定 BASE，然後檢視：

git log "$BASE"..HEAD --oneline
git diff "$BASE"...HEAD

如果在 main 或 master 上，請先建立功能分支。確保預期的變更已提交，並檢視整個分支差異，而不僅是最新提交或現有 PR 文字。

核心規則

• 在實作細節之前，描述具體的變更行為、受影響的範圍以及對審查者的影響。
• 僅在有用時說明動機、風險、取捨、遷移或審查重點。
• 使用能讓變更更容易審查的最小結構。
• 將內部提示或流程術語替換為具體行為。
• 更新 PR 時，根據當前完整差異重新撰寫，不要敘述審查歷史。

標題

使用 <type>(<scope>): <subject> 或 <type>: <subject>。

允許的類型：feat、fix、ref、perf、docs、test、build、ci、chore、style、meta、license 和 revert。

• 使用最精確的類型和範圍描述整個分支的主要變更。
• 僅在變更破壞外部合約時使用 !，並在內容中說明受影響的範圍。
• 避免模糊的主題，例如 update、cleanup、misc、fix stuff 或 address feedback。不要加上句尾句點。
• 僅在現有標題仍能描述整個差異時保留它。

內容結構

選擇最小有用的結構：

變更類型	應包含內容
小型或顯而易見	一個簡潔的段落，無需標題。
功能、錯誤修正或重構	變更的行為與影響；必要時加入根本原因、未變更的行為或非顯而易見的做法。
合約或破壞性變更	受影響的 API、結構、負載、設定、權限、儲存或 CLI 範圍；包含相容性與遷移指引。
操作、視覺或流程變更	使用者/操作員的影響、可量化的影響、失敗模式或流程（若有用）。
廣泛、自動生成或跨領域變更	組織原則、為何需要如此廣泛，以及審查應從何處開始。

預設格式：

<變更了什麼以及產生了什麼影響。>

<為何採用此做法、風險、遷移或審查重點（若非顯而易見）。>

對於審查意見回饋的更新，將最終的 PR 作為整體描述，而非一系列修訂。

審查輔助工具

僅在能減少審查者重建工作時使用輔助工具：

• 針對變更的合約，提供簡潔的前後對比或介面範例。
• 針對非同步流程或狀態轉換，提供小型 Mermaid 圖表。
• 當有視覺證據時，提供螢幕截圖或錄製說明。
• 當審查者或採用者需要時，提供部署、相容性、風險或審查順序的說明。

用一句話說明審查者應注意的重點，並在文字更清晰時省略輔助工具。

邊界

• 不要加入預設的 Summary、Changes 或 Test Plan 章節。
• 省略例行驗證，除非它改變風險評估或解釋重要的回歸測試覆蓋。對於文件、技能、文案或設定變更，預設省略。
• 不要貼上指令、CI 記錄、驗證輸出、提交記錄、佔位符或詳盡的檔案列表。
• 絕不包含客戶或組織名稱、使用者電子郵件、支援單內容、機密或個人識別資訊。
• 僅在從使用者輸入、分支名稱、提交、PR 討論或追蹤工具驗證後，才使用問題參考。Fixes <issue> 會關閉問題；Refs <issue> 僅連結。

建立或更新

將新 PR 建立為草稿。將內容寫入暫存 Markdown 檔案，然後執行：

gh pr create --draft --title '<title>' --body-file /tmp/pr-body.md

使用 gh api 更新現有 PR：

gh api -X PATCH repos/{owner}/{repo}/pulls/PR_NUMBER \
  -f title='<title>' \
  -F body=@/tmp/pr-body.md

當後續提交實質上改變範圍、做法、破壞性行為、風險、遷移或審查期望時，更新標題與內容。跳過僅修正錯字、格式或重新命名的後續提交。

範例

小型變更：

AI 自訂區段現在預設為摺疊，以免在使用者需要之前佔用側邊欄空間。展開後會保留現有的已儲存偏好設定行為。

破壞性合約：

執行記錄現在輸出區塊層級的記錄，而非單一技能層級的記錄。讀取頂層 `findings` 的消費者必須對每個記錄迭代 `chunk.findings`。

之前：

```json
{"skill": "security-review", "findings": [...]}
```

之後：

```json
{"schemaVersion": 1, "chunk": {"index": 1, "findings": [...]}}
```