pr

/pr — 總結工作並維護 PR

請依照以下步驟執行：

Step 1: 分析當前工作

1a. Git 分析

1. 執行 git status 和 git diff（staged + unstaged）了解未 commit 的變更
2. 執行 git log 查看近期 commit 風格
3. 關鍵步驟 — 同步遠端並確認 PR 完整範圍：
   • 先執行 git fetch origin（⚠️ Stale Local Branch 陷阱：本地的 master/main/hotfix 可能落後遠端數十個 commits，忘記 fetch 會把已經 merge 的 commits 算進 PR 範圍，導致 description 嚴重失準）
   • 執行 git log --oneline origin/<base-branch>..HEAD 查看 PR 包含的所有 commits（永遠用 origin/<base-branch> 比較，不要用本地 <base-branch>）
   • 執行 gh pr diff <PR-number> --name-only 查看 PR 涉及的所有檔案
   • 如果已有 open PR，執行 gh pr view <PR-number> --json body 讀取現有 description
   • 交叉驗證： 比對 git log 結果與 gh pr diff 結果，若差異過大（例如 git log 顯示 50+ commits 但 gh pr diff 僅 1-2 files），以 gh pr diff 為準並重新檢視

1b. 對話脈絡分析

回顧本次對話的完整內容，提取以下 context 項目（這份清單是本 skill 唯一權威清單，Step 5 撰寫 PR description 時逐條比對，不重新定義）：

1. 動機：使用者最初提出的問題或需求是什麼？
2. 討論過程：過程中探索了哪些方案？做了哪些比較或調查？
3. 決策點：哪些地方有多個選擇？最終為什麼選擇這個方案？
4. 放棄的嘗試：有沒有試過但放棄的做法？為什麼放棄？
5. 隱含知識：對話中出現但不會反映在 diff 裡的重要 context（例如：調查數據、外部工具比較、效能考量）
6. 業界/學術依據：技術決策是否引用業界標準（RFC、OWASP 等）或學術研究？
7. 社群共識與反面意見：對話中是否討論過社群主流看法、已知的反面意見或陷阱？
8. Ticket 參照：掃描對話中是否出現 [A-Z]+-\d+ 編號（如 JIRA-123）、Notion URL、或「Notion Ticket」字樣，記錄找到的編號與票名（供 Step 5 PR 標題使用）
   • PDT ticket（Linear，強制）：另外掃這四個來源的 PDT-\d+（大小寫不拘）：對話內容、當前 branch 名（git branch --show-current，如 fix/pdt-11061-...）、origin/<base-branch>..HEAD 的 commit message、既有 PR 的 title／body。命中後一律正規化成大寫 PDT-<number>，只記在這條、不重複列進上面的通用 ticket 清單，記進 Context Manifest，並往下傳給 Step 3.5（branch 命名）與 Step 5（PR 標題）。有多張就全部列出
   • 只算這次工作對應的票：舉例、引用別的 PR 標題、blocked by／相關票這類順帶提到的編號不算。對話裡出現多個編號、又分不出哪張才是這次的工作，用 AskUserQuestion 讓使用者選，不要猜

⚠️ 常見錯誤：只看 git diff 會遺漏 PR 中其他 commits 的內容；只看 diff 不看對話會遺漏「為什麼這樣做」的決策脈絡。PR description 必須同時反映 what changed（diff） 和 why it changed（對話 context）。

Step 1b 結束時建立「Context Manifest」，供 Step 5 逐條比對：

## Context Manifest（Step 1b → Step 5 交接）

| # | Context 類型 | 摘要 | 已寫入 PR Description？ |
|---|------------|------|------------------------|
| 1 | 動機 | 使用者原始需求 xxx | 待比對 |
| 2 | 放棄的方案 | 考慮過 A 但因 B 放棄 | 待比對 |
| 3 | 決策依據 | 選 X 不選 Y，因為 Z | 待比對 |
| ... | ... | ... | 待比對 |

expected_count = N（對話中識別的 context 項目總數）

1c. 總結

綜合 git 分析 + 對話脈絡，總結本次工作的目的、做了什麼、為什麼這樣做。

Step 2: Quick Review

對所有變更進行快速 code review，檢查以下項目：

檢查清單

• 安全性：是否有敏感資訊外洩（API keys、secrets、.env 內容）
• 正確性：邏輯是否正確、有無明顯 bug
• 遺漏：是否有 debug code（console.log、debugger）未清除
• 型別：TypeScript 型別是否正確、有無 any 濫用
• 樣式：是否符合專案既有 coding style
• 視覺驗收面：變更是否觸及 UI 視覺／互動行為？觸及則列出「待截圖驗收項目」草稿（一項一個可判 PASS/FAIL 的斷言），交給 Step 5.5 收尾；未觸及則明示「無視覺面，Step 5.5 將跳過」

主動安全審查（依 rules/security-guidance/skill-integration.md 的觸發閘）

判斷變更是否觸及安全敏感面（認證/輸入/endpoint/DB/反序列化/檔案/shell/SSRF/DOM/加密，定義見上述文件）：

• 觸及 → 委派內建 /security-review skill 審查當前 branch 的 pending changes，判準以 ~/.claude/claude-security-guidance.md 為準；findings 併入下方輸出，CRITICAL/HIGH 在「互動確認」中提示先修正
• 未觸及 → 明示「無安全敏感面，跳過」
• 若從 /update 串接：Step 2 已含安全審查，此處不重複委派（去重）。但**「視覺驗收面」判定不在 /update 涵蓋範圍**——即使跳過本步驟其餘檢查，該判定仍要做（或由 Step 5.5a 直接從 gh pr diff --name-only 補判），否則 Step 5.5 會無輸入而誤跳過

輸出格式

用簡潔的表格或清單呈現 review 結果：

• ✅ 沒問題的項目一句帶過
• ⚠️ 有疑慮但不阻擋的項目說明原因
• ❌ 必須修正的問題列出檔案和行號

互動確認

Review 完成後，使用 AskUserQuestion 詢問使用者：

• 繼續 PR 流程：review 結果沒問題，繼續 commit → push → PR
• 先修正問題：先處理 review 發現的問題，修完再重新執行 /pr

如果使用者選擇「先修正問題」，則根據 review 結果逐一修正，修正完後重新從 Step 1 開始。

Step 2b: 自動修正

若 Step 2 發現可自動修正的問題（dead code、命名、nesting、重複程式碼），委派內建 /simplify skill 執行；未發現則跳過。

Step 2c: Plan 歸檔檢查

在 commit 之前，若本次對話涉及的 plan 已完成（plans/active/*.md 的 Status 為 COMPLETED/完成，或所有 Phase/Step 皆標記 [x]/✅），呼叫 /plan-archive skill 歸檔至 plans/completed/；沒有已完成的 plan 則跳過。

Step 3: Commit 當前變更

1. 如果有未 commit 的變更，根據變更內容撰寫 commit message
2. 使用 conventional commits 格式（feat / fix / chore / refactor / test / docs），英文撰寫
3. 確保不要 commit 敏感檔案（.env, credentials 等）

Step 3.5: PDT ticket 與 branch 名（Step 1b 有找到 PDT 才做）

branch 名要帶 ticket，格式 <type>/pdt-<number>-<kebab-slug>（例：fix/pdt-11061-editor-toolbar-keyboard-sticky），<type> 沿用 conventional commit 前綴。沒找到 PDT 就跳過本步驟。

當前狀態	動作
branch 名已含 pdt-<number>（大小寫不拘）	符合，直接進 Step 4
還在 base／long-lived branch 上（main、master、hotfix、develop*、release-*）	直接用上面格式開新 branch，不要改 long-lived branch 的名字
自己的 branch、還沒推上遠端也沒有 PR	用 AskUserQuestion 提議 git branch -m <新名>，選項「改名（推薦）」／「維持原名」
已推上遠端或已有 PR	不改名（重推新名會讓既有 PR 斷掉），ticket 改由 PR 標題承載，Step 6 回報時註明 branch 名沒帶 ticket

Step 4: 推送到遠端

有 remote tracking branch 用 git push；沒有則 git push -u origin <branch> 建立。

Step 5: 建立或更新 PR

Base Branch 防護（強制執行）

PR 的 base branch 禁止直接指向主要的 production branch（如 master、main）。

執行以下檢查：

1. 讀取專案的 branch 策略（如果有 skills/git-workflow/SKILL.md 或類似文件）
2. 如果專案有定義預設的 base branch（如 hotfix、develop），自動使用該 branch
3. 如果使用者明確要求指向 master 或 main → 必須中斷並警告：
   • 使用 AskUserQuestion 提醒：「依照專案規範，PR 不建議直接指向 master/main。確定要繼續嗎？」
   • 提供選項：「改為 [專案預設 base branch]（推薦）」/「我確定要指向 master/main」
   • 只有使用者明確確認後才能繼續
4. 如果專案沒有特別的 branch 策略，使用 repo 的 default branch

# 範例：專案規範 base branch 為 hotfix
gh pr create --base hotfix ...

# 禁止（除非使用者明確確認）
gh pr create --base master ...

CHANGELOG 檢查（Release PR 專用）

當 base branch 為 master 或 main 時，必須檢查 CHANGELOG.md：

1. 確認專案根目錄是否有 CHANGELOG.md
2. 如果有，檢查最新條目是否涵蓋本次 PR 的變更：
   • 讀取 CHANGELOG.md 最新版本區塊
   • 比對 git log origin/<base-branch>..HEAD --oneline 的 commits
   • 如果有 commits 未被記錄在 CHANGELOG 中 → 使用 AskUserQuestion 提醒：

     CHANGELOG.md 尚未包含以下變更：

     • <未記錄的 commit 摘要>

     1. 幫我更新 CHANGELOG — 自動補上缺少的條目
     2. 跳過 — 不更新 CHANGELOG，繼續 PR 流程

3. 如果專案沒有 CHANGELOG.md，跳過此步驟

PR Title 格式

依據 base branch 和 ticket 參照決定 PR 標題：

Release PR（base branch 為 master/main）

當 PR 的 base branch 為 master 或 main 時，標題必須使用 Release 格式：

• 格式：Release vX.Y.Z: <摘要>
• 範例：Release v1.18.0: add skill defer + CHANGELOG updates
• 版本號推斷優先順序：CHANGELOG.md 最新版本 → package.json version → git tag
• 摘要從 PR 包含的 commits 中提取主要變更，簡短描述即可
• Step 1b 有找到 PDT ticket 時，把編號全部附在標題尾巴：Release v1.18.0: <摘要> (PDT-10980 PDT-10779)

更新既有 PR 時，也必須檢查 title 是否符合此規則，不符合則一併更新。

一般 PR（base branch 非 master/main）

使用 Step 1b 提取的 ticket 參照決定 PR 標題：

• 有找到 PDT ticket → 標題必須帶字面上的 PDT-<number>，只寫票名不算數。預設放在尾巴：fix(kyc): 注意事項清單改 inline style (PDT-10908)。若 repo 慣例是寫進 scope（fix(PDT-11061): ...）也可以。多張票全部列出：(PDT-10980 PDT-10779)
• 有找到其他 ticket（不含 PDT，PDT 一律走上一條）→ 標題必須包含 ticket 資訊，二擇一：
  1. 標題末尾附上 ticket 編號：fix(seo): add noindex for empty about page (TICKET-1234)
  2. 標題包含票名：fix(seo): [Bug] empty about page should be no-indexed
• 沒找到 ticket → 正常標題，不需額外處理

更新既有 PR 時，也要檢查 title 有沒有漏掉 PDT 編號，漏了就用 gh pr edit --title 補上。

判斷邏輯

• 如果提供了 PR 號碼（$ARGUMENTS），更新該 PR
• 如果沒有提供號碼，檢查當前 branch 是否已有 open PR
  • 有 → 更新該 PR description
  • 沒有 → 建立新 PR（使用專案規範的 base branch）

PR Description 格式

PR description 必須包含以下區塊，使用繁體中文撰寫：

## Summary

<!-- 1-3 句話說明這個 PR 的目的和背景脈絡，讓 reviewer 30 秒內理解「為什麼要做這件事」 -->

## Context（對話脈絡）

<!-- 最重要的區塊。內容依 Step 1b 的 Context Manifest 逐條寫入，來源優先序：對話脈絡 > git diff > commit messages -->
<!-- 目標：reviewer 不需要問「為什麼這樣做？」就能從這裡找到答案 -->

## Changes

<!-- 按主題分類列出變更，涵蓋 PR 的所有 commits（不只是當次對話的工作） -->
<!-- 用 git log origin/<base-branch>..HEAD 確認完整範圍（必須先 git fetch origin） -->
<!-- 用 git diff origin/<base-branch>..HEAD --diff-filter=D --name-only 確認刪除的檔案 -->
<!-- 本次對話沒親自做過的 commit（跨 session 累積的 branch、更新既有 PR）：其條目的
     「改了什麼」必須對 git diff 核實，commit message 只用來定位該查哪段 diff，不能當證據；
     核不到佐證的標「無法佐證」列出來，不要為了讓 body 看起來完整而放寬。
     當次對話親自做的照舊（diff 就在對話裡，不必重查）。 -->
<!-- 每個主題明確標示：新增了什麼、刪除了什麼、修改了什麼 -->

## Test plan

<!-- 測試計畫，checkbox 格式 -->
<!-- 若 Step 2 判定有視覺面，此處列出待截圖驗收的編號項目（B1/C1…），並在 Step 5.5 完成後回頭勾選；
     移除／重構類不要列截圖項，改列量測項（grep 殘留、bundle diff、目錄不存在） -->

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Manifest 逐條比對： 撰寫完 Context 區塊後，逐條比對 Step 1b 的 Context Manifest，確保每個項目都已反映；差集（expected_count − actual_written）> 0 的項目必須補齊，不可遺漏。

Evidence Gate（寫回前，強制）

description 定稿後、執行 gh pr create/gh pr edit 前，呼叫 evidence-gate skill 過關卡：commit range 固定 origin/<base-branch>..HEAD（沿用 Step 1a 已 git fetch origin 的範圍），description 每條事實宣稱拆成該 skill 第 1 節的 Claim Schema，證據一律溯源 git diff/git log --numstat，commit message 僅供定位不當證據；並依其第 4 節派 fresh-context subagent 對抗性複驗。零 FAIL 且零 SCHEMA-DEFECT 才可繼續下方 gh pr create/gh pr edit；任一 FAIL 或 SCHEMA-DEFECT 回本節修正 description，不寫回 PR。

Skill({ skill: "evidence-gate" })

Step 5.5: 截圖驗收 gate（PR 已存在後執行）

PR 建立／更新完成後，判斷本次變更是否需要截圖驗收，需要就用 AskUserQuestion 取得授權再跑。 這步在 Step 5 之後才做：截圖要貼成 PR comment，PR（與 preview env）不存在就沒有落點。

適用範圍不限於由 /pr 建立的 PR。 若 PR 由派工 agent 或手動 gh pr create 建立， 派工者仍須在 PR 存在後補跑本步驟——委派出去的是工作，不是責任。 這個 gate 只寫在 /pr 裡，所以繞過 /pr 的路徑會讓它靜默消失； 而「請 agent 開 PR」正是最常見的繞過方式。

特別要抓的一種狀態：截圖已經拍了、trace 也存了，但全部落在 .verification/ 之類的本機路徑。 證據存在卻停在 reviewer 打不開的地方，等同沒有證據——這正是 /pr-evidence-comment 要解決的問題本身。

5.5a 分類（沿用 /pr-evidence-comment Step 0 的同一張表）

以 Step 2 的「視覺驗收面」判定與 gh pr diff <PR> --name-only 為依據分類：

變更類型	驗收手段	本步驟動作
UI 視覺／互動行為	headed 截圖	進 5.5b 詢問
狀態遷移後「行為不變」	截圖（證沒壞）＋ 量測（證真的遷了）	進 5.5b 詢問，並提醒量測項不可省
純移除／重構	量測（grep 殘留、bundle diff、目錄不存在）	不問截圖，直接提示補量測項到 Test plan
API／資料正確性	curl／測試輸出	不問截圖，直接提示補測試輸出
純文件／設定／CI	無	明示「無視覺面，跳過」

移除類拍不出來：截圖只能顯示「看起來正常」，證不了「東西真的不在了」。別為了有圖而追截圖。

5.5b 互動確認（AskUserQuestion）

判定為「需要截圖驗收」時，必須用 AskUserQuestion 詢問，不可自行決定跑或不跑（會開瀏覽器、要人工登入、且會以使用者身分公開發 comment）。

問題帶上：偵測到的視覺面變更檔案、Step 2 草擬的驗收項目編號清單、以及可用的驗收環境（preview URL／staging／local）。選項：

1. 現在就驗（推薦） — 委派 /pr-evidence-comment，帶入驗收項目清單與環境 URL
2. 只列清單，我自己驗 — 把編號清單寫進 PR 的 Test plan（未勾選），不開瀏覽器
3. 這次不需要 — 記錄理由並在 PR 補一句說明為何免視覺驗收

環境判定：base 為專案預設分支且 repo 有 preview 部署慣例時，先確認 preview env 是否就緒（例如 PR 需要特定 label 才部署）。未就緒不要硬跑——改問使用者要「等 preview 好了再驗」還是「先用 local 驗」。

5.5c 執行與回填

使用者選 1 → 用 Skill tool 委派：

Skill({ skill: "pr-evidence-comment" })

該 skill 跑完（截圖已上傳、gh pr view 驗證過 user-attachments 數量相符）後回到本步驟：

• 把逐項 PASS/FAIL 結論回填 PR description 的 Test plan（勾選已驗項目）
• FAIL 項目不可當成「已驗收」帶過——列出來並回到修正流程
• 驗收結論同時回貼 PR comment（由該 skill 完成），對話裡只做摘要
• 這次回填不必重跑 Step 5 的 evidence-gate：證據就是剛產生的截圖與 comment 連結，回填時直接引用；但 Test plan 只能寫實際驗過的項目，未驗的維持未勾選

使用者選 2 或 3 → 依選項寫回 Test plan／說明，不呼叫該 skill。

Step 6: 確認結果

1. 輸出 PR URL
2. 確認 PR description 已更新
3. 回報 Step 5.5 的結果：已截圖驗收（附 comment 連結）／已列清單待人工驗／判定免驗（附理由）／無視覺面
4. 回報 PDT ticket 放在哪裡：偵測到的編號與出處、PR 標題有沒有帶、branch 名有沒有帶。沒帶的話講原因（例如 branch 已推上遠端，不改名）。沒找到 PDT 就明說「未偵測到 PDT ticket」
5. 如果有相關的其他 PR（如 feature → develop、develop → master），檢查是否需要同步更新

使用方式

/pr # 自動偵測是否有 open PR，沒有就建新的 /pr 7195 # 更新指定 PR 的 description