jeffyfung/skills

提交、推送並開啟 PR

將目前功能分支的工作送出：提交 → 推送 → PR。第 6 步的確認閘門控制推送 —— 即使在同一回合中重複呼叫，也絕不能跳過。

接受一個選用引數：基底分支。若未提供，第 5 步會解析出基底。

1. 保護分支

git branch --show-current。如果是 main/master，請停止並請使用者先建立功能分支 —— 絕不能直接對 main 進行提交或推送。

2. 確定提交範圍

git status + git diff。僅暫存屬於當前任務的檔案。看起來像暫存輸出、產生的資料或本機測試 fixture 的未追蹤檔案（CSV、*_results/*、日誌）不會自動暫存 —— 列出它們，並詢問使用者是要包含、忽略還是加入 .gitignore。

3. 提交前檢查

查閱儲存庫自身的格式／lint 指令 —— 依序檢查 AGENTS.md、CLAUDE.md 和 README.md（依此順序），尋找其中記載的格式化工具/linter，並執行指定的工具。如果這些文件中都沒有提到任何格式化工具/linter，則不要預設使用 dotnet format 或其他任何特定工具 —— 請註明沒有記載任何格式化工具/linter，然後繼續。

如果變更觸及已測試的程式碼，且有可用的快速目標測試，請執行該測試；不要為了提交而執行完整的測試套件。

4. 提交訊息

Conventional Commits (feat|fix|test|docs|refactor(scope): summary)，比對此儲存庫 git log 中已有的風格。只有在「為何」無法從 diff 中明顯看出時才加入主體。

5. 解析基底分支

基底為 main，除非工作是堆疊的 —— 建立在尚未合併的功能分支之上，此時若以 main 為基底，會將下方分支拖入此 diff。

1. 已給定引數 —— 那就是基底。使用 git rev-parse --verify origin/<base> 驗證；如果該 ref 不存在，請告知並使用 main。
2. 未給定引數 —— 搜尋一個候選分支。以下任一條件符合：
   • 對話內容指出此工作位於另一個分支的提交之上。
   • 此工作來自一個被另一個票證封鎖或依賴另一個票證的票證 —— 解決該封鎖者的分支就是候選分支。
   • git log --oneline origin/main..HEAD 顯示此任務未產生的提交；git branch -r --contains <sha> 會指出這些提交的來源。
3. 驗證候選分支。 它必須存在於遠端、與目前分支不同，且未出現在 git branch -r --merged origin/main 中 —— 已合併到 main 的候選分支是無效的。
4. 沒有候選分支，或驗證失敗 —— 使用 main。

通過驗證的候選分支僅是建議，而非決定：在第 6 步的閘門處，將其與 main 一同提供，讓使用者選擇。

6. 確認閘門 —— 推送

向使用者顯示提交訊息、git diff --stat（或建立後的提交），以及第 5 步得出的基底 —— 如果第 5 步找到候選分支，則兩個選項都要顯示。在獲得明確同意之前，不要執行 git push -u origin <branch>。推送會將分支公開 —— 請將其視為單向操作。PR 的建立依賴於同一確認（參見第 7 步），不需要額外的核准。

7. 開啟 PR

首先檢查此分支是否已有 PR：gh pr list --head <branch> --state all。

• 找到已開啟的 PR —— 重複使用它，不要建立重複的 PR。回報其 URL。
• 找到已合併的 PR —— 該分支已被送出一次；請停止，並詢問使用者他們想做什麼，然後再建立另一個 PR（合併後又有新提交的情況並不常見，這不是預設情況）。
• 沒有現有／已合併的 PR —— 第 6 步的推送確認已涵蓋此情況：直接草擬主體並執行 gh pr create --base <base> --head <branch> --title "<title>" --body "<body>"，不需要額外的核准。

可見 UI 變更的螢幕截圖。 如果變更會變更使用者看得見的任何內容 —— 新的文字欄位、顏色變更、新的版面或文案、新頁面或元件 —— 請為快樂路徑以及此變更引入的邊界情況（空狀態和錯誤狀態、長／溢出文字、響應式與桌面版（如相關））拍攝螢幕截圖。使用 gh pr create --attach '<path>#<alt text>' 上傳它們（重複每個圖片；對現有 PR 使用 gh pr edit <pr> 來追加）。如果主體引用了相同的路徑 —— 例如在 ## Screenshots 標題下的 ![Happy path](./pr-shots/happy.png) —— gh 會將參考連結原地替換為已上傳的 URL；否則附件會附加在主體的結尾處。這也適用於私有儲存庫：任何有儲存庫存取權限的人都能看到附件。請將檔案留在提交之外（使用暫存目錄）—— 它們是上傳的，而不是受版本控制的。需要 gh ≥ 2.99；在較舊版本上，請將圖片拖放到網頁 UI 的 PR 主體中。僅當變更對使用者無感時（邏輯、測試、設定、文件、CI）才跳過此步驟。

在草擬之前，請檢查儲存庫是否有自己的 PR 說明標準 —— .github/PULL_REQUEST_TEMPLATE.md、.github/pull_request_template.md、docs/* 或關於 PR 主體的 CONTRIBUTING.md 指引。儲存庫記載的範本會覆蓋下方的範本；請改用該範本。

PR 主體範本（後備 —— 如果儲存庫有自己的標準，則以該標準為準）

## 摘要
<變更了什麼以及原因，1-6 句話>

## 變更
- <值得注意的變更 1>
- <值得注意的變更 2>

## 螢幕截圖
<針對可見的 UI 變更：快樂路徑 + 相關邊界情況；針對不可見的變更，請省略>

## 設計決策
<值得注意的權衡或已否決的替代方案 —— 僅針對大型功能變更，請參閱下文>

## 測試
<執行的指令／驗證方式>

## 後續工作
<暫緩的工作，或「無」>

當基底不是 main 時，請在摘要中說明基底分支的名稱以及必須先合併的內容 —— 審查者需要知道 diff 是堆疊的，且此 PR 會在基底合併後重新定位至 main。

僅當 PR 引入真正規模的新功能行為（新模組、非平凡的演算法、審查者本來必須詢問的權衡）時，才包含設計決策 —— 對於文件／設定／雜務／小型修正，請完全省略該區段，而不是讓它留空。

8. 審查導覽（僅限大範圍變更）

當以下任一條件成立時，請撰寫一個自包含的 HTML 導覽：

• diff 觸及多個不同的非 UI 模組；
• 它變更了資料庫結構描述（遷移、資料表、欄位、索引、條件約束）；
• 它是一個大型端到端功能（跨越數個層級的新流程）。

對於文件、設定、雜務、小修正以及僅限於一個模組或僅 UI 的變更，請跳過。此導覽是為了縮短審查時間 —— 請不要為每個 PR 自動產生它。

在提交之外的暫存目錄中建立一個檔案 pr-walkthrough.html（絕不能暫存它），使用 open pr-walkthrough.html 在本機開啟它，並將路徑提供給使用者。不要託管它、附加它或對其進行版本控制。

將其結構化為原生 <details>/<summary> 可折疊標題下的區段 —— 第一個區段展開，其餘區段折疊 —— 以便審查者掃描標題並只展開他們需要的部分。不需要 JavaScript。

為尚未閱讀 diff 的審查者撰寫：

• 變更內容與原因 —— 用幾句話說明變更，以及閱讀 diff 的順序。
• 變更地圖 —— 觸及了哪些模組，以及它們如何連接。一個圖表，而不是檔案列表。
• 機制 —— 每個不明顯的邏輯或資料流，在提到的程式碼旁邊（path:line）說明。
• 結構描述變更 —— 變更前後的資料表形狀、遷移路徑以及風險（鎖定、回填、回滾）。
• 困難部分 —— 審查者本來必須詢問的部分，以及需要仔細審查的內容。

圖表：內嵌 SVG，手寫並根據內容調整大小，用於模組依賴關係、請求／序列流程和結構描述。保持檔案自包含 —— 沒有外部 JS、CSS 或圖片 URL，以便離線開啟。僅在說明的內容是視覺性的情況下，才使用渲染圖或螢幕截圖。

9. 回報

將 PR URL 及其目標基底提供給使用者。清楚說明提交、推送和開啟了什麼 —— 不要含糊其辭。