Plain-English PR 描述是做什麼的？

為需要快速理解變更的維護者而寫。好的描述在第一個畫面回答三個問題：

哪裡錯了或缺少什麼？
為什麼需要改變？
改變後的情況為何？

在撰寫前，請閱讀實際的 diff、當前 PR body、commit、測試與 PR 狀態。舊的 body 與 commit 標題描述的是意圖，而非證據。除非作者確認，否則不得聲稱已進行手動測試、部署或生產行為。

必要開場：變更內容與原因

每一份 PR 描述都必須以貢獻者擁有的 ## What Changed and Why 區段開頭，若監控者已擁有 ## Status 區段，則緊接在該區段之後。這是必要格式，而非可選樣式。

使用三個簡短的標籤段落，按此順序：

Issue： 實際的使用者或操作員失敗，或缺少的行為。
Why this change was necessary： 該失敗為何重要，以及為何需要這個變更邊界。
New status quo： 此 PR 合併後的具體行為。

每個標籤段落保持一兩句話。維護者應能僅從此區段回答「這個 PR 發生了什麼？」。不要以實作機制、已刪除的設計或改寫歷史開頭。

當審查不夠充分的開場時，請提供具體的替代方案或針對實際 diff 的簡潔三段大綱。不要只說它冗長、不清楚或需要更好的解釋。

對大多數 PR 使用此結構：

## What Changed and Why

**Issue：** [實際的使用者或操作員失敗，或缺少的行為。]

**Why this change was necessary：** [為什麼重要以及為何需要這個邊界。]

**New status quo：** [此 PR 合併後的具體行為。]

## After merge

[僅保留真正的操作員或審查者後續動作。如果沒有則省略此區段。]

## Verification

[僅陳述已確認的手動檢查與真正需要合併後進行的檢查。]

從實質內容開始。不要重述 PR 標題、加上介紹，或寫出重複下一個段落的摘要。

應保留的內容

每個實質變更一個明確的最終狀態。 掃讀每個段落或項目符號的第一句話，讀者應能了解合併後變更了什麼。
真實的決策。 僅在影響產品行為、風險或顯著成本時，才提及被拒絕的替代方案。用一句話說明選擇了什麼與原因。不要製造「Key decision」標籤。
操作事實。 當審查者或操作員需要據以行動時，提及遷移、回填、排程任務、整合、密鑰、部署順序與失敗行為。
誠實的驗證。 區分實際手動檢查的項目與確實必須等到合併後才能進行的工作。不要列出 lint、建置、CI 或測試指令。當測試涵蓋有意義的行為時，可以用平實的英文提及。
開放問題。 僅包含審查者必須決策的未解決事項。先提出問題，再給出建議及其成本。若無需決策則省略此區段。

變更系統的必要證據

當 PR 變更了使用者面向的系統、重要的操作員工作流程或其配置，且未向審查者展示如何檢查時，描述就不完整。

截圖或短片： 將視覺證據放在獨立的 ## Visual evidence 區段。若變更了畫面則包含截圖；若變更了互動或多步驟流程則包含短片。嵌入媒體或連結到穩定的 PR 附件。說明文字必須說明變更了什麼以及審查者正在看什麼。不要用原始碼截圖、測試報告或未變更的畫面來替代。對於公開與活動表面，在筆電證據之前先放手機證據，並標明每個視口與測試狀態。依照 visual-proof 技能進行擷取、上傳與最新 commit 驗證。僅在 PR 沒有視覺或互動表面時才省略此區段。
配置、環境與遷移： 僅將真正新增、移除、重新命名或行為變更的環境變數、密鑰、儀表板設定與資料庫遷移放入 ## Configuration。以操作員需要採取的一個動作開頭；將一般的外部設定維持在一句簡短的描述，例如：Set up a monitor at <URL> and point it to https://buildpurdue.org/api/health. No internal changes. 不要用輪詢細節、已在別處解釋的理由或重複的操作手冊連結來填充此區段。對於每個真正的遷移，命名其 committed 的 supabase/migrations/ 路徑，總結綱要/資料/策略變更，說明相容性或回填需求，並給出已確認的 npm run db:verify 重播結果。切勿印出密鑰值。若沒有配置或遷移變更則省略此區段。
變更的流程： 對會變更的重要流程使用 Mermaid 流程圖。當流程包含多個步驟、分支、重試、系統間交接或失敗路徑時即屬重要。顯示變更的路徑及其重要的失敗行為，使用審查者能閱讀的平實標籤。每個不同的變更流程加入一個圖表。不要為單一步驟的重新命名或簡單的區域計算使用圖表。

這些與主要說明分開。說明解釋變更存在的原因；證據、配置與圖表讓審查者能夠檢查。

保持可讀性

預設 250 字以內。當操作員需要簡短檢查清單時，描述可以更長，但每句話都必須有存在的價值。
使用短段落。僅在真正需要列出事項時才使用項目符號，例如剩餘的設定步驟。不要將每句話都變成帶標籤的項目符號。
用平實的英文描述問題、原因與新現狀。說出誰做了什麼。
避免原始碼、查詢、配置片段、作為名詞用的狀態碼、行話、隱喻、誇大詞語與長破折號。
不要解釋每個機制。僅保留審查者需要知道的行為。
不要在後面的區段重複之前的事實。如果一句話可以刪除而不遺失資訊，就刪除它。

Status 由監控者擁有

貢獻者擁有 PR 描述的所有部分除了 ## Status。不要自行新增、移除或編輯該區段。BuildPurdue PR 監控者擁有它，並使其與當前審查狀態保持一致。

當監控者變更 Status 時，也會發布一個對應的 Status update： PR 評論。它使用一句平實的英文：當仍有工作時，為合併前的具體下一步動作；當沒有剩餘工作時，則為 No more remaining work.。Status 絕不屬於面向貢獻者的描述審查評論。

不要在 Status 中使用選擇性的未來想法、歷史記錄、僅在合併後進行的工作，或已另外追蹤且不阻礙此 PR 的工作。

當需要更多結構時

僅在資訊無法放入主要說明時，才加入聚焦的區段：

Database / migrations： 必須執行什麼、現有資料是否仍相容、是否需要回填。
Operational behavior： 什麼會執行、何時執行、失敗如何可見、操作員必須配置什麼。
Verification： 已確認的手動檢查與真正合併後才進行的檢查。
Open calls： 未解決的產品或風險選擇。

小型錯誤修復可以直接使用：

## Root cause

## Fix

## Verification

發布前

檢查每個聲明都能追溯到當前的 diff、測試、PR 狀態或你執行的指令。
單獨閱讀第一個畫面。它必須清楚說明問題、變更原因與新的現狀。
移除歷史敘述、變更日誌式的實作記錄、重複的說明與無關的工作。
確認任何遷移、部署、密鑰、儀表板或合併後動作都已明確且可行。
大聲讀出來。它應該聽起來像一個人在向隊友解釋變更，而不是一份稽核報告。
每次推送時，將 body 與新的 diff 進行比較，並在行為、剩餘設定或驗證狀態發生變化時更新。

來源

在 .agents/skills/ 下編輯此副本。pre-commit hook 會將其鏡像到 .claude/skills/pr-description/；請勿直接編輯鏡像。

Plain-English PR 描述