skills/code-review-resolve/SKILL.md

@@ -1,19 +1,20 @@
 ---
 name: code-review-resolve
-description: 解決 `.gitea/ai-review/findings.json` 的 AI review findings，依嚴重度逐條修復或標示待人工處理，完成後清空 findings；接著可將工作區變更依 conventional commit 類型分類提交、push 當前分支，並透過 Gitea API 對指定目標分支開 PR。當使用者說解決 findings、處理 AI review 問題、修掉 `.gitea/ai-review` 問題、依嚴重度修復後分類提交，或要分類 commit 並 push/開 PR 時觸發。不適用於：產生 findings、單純 code review 不修改、只保存裁決紀錄，或只要不分類的單一 commit。
+description: 解決 `.gitea/ai-review/findings.json` 的 AI review findings，先同步 git（fetch → pull，必要時嘗試解衝突），再依嚴重度逐條修復或標示待人工處理，完成後清空 findings；接著可將工作區變更依 conventional commit 類型分類提交、push 當前分支，並透過 Gitea API 對指定目標分支開 PR。當使用者說解決 findings、處理 AI review 問題、修掉 `.gitea/ai-review` 問題、依嚴重度修復後分類提交，或要分類 commit 並 push/開 PR 時觸發。不適用於：產生 findings、單純 code review 不修改、只保存裁決紀錄，或只要不分類的單一 commit。
 argument-hint: "[--findings <findings.json 路徑>] [--target <目標分支>] [--pr-desc <full|simple|自訂文字>] [--no-commit] [--no-pr] [--yes]"
 ---
 
 # code-review-resolve — 解決 AI review findings、分類提交、push 並開 PR
 
-四階段 skill：先**逐條修掉** `.gitea/ai-review/findings.json` 裡的問題並清空該檔，再把工作區所有變更**依 conventional commit 類型分門別類 commit**，接著 **push 當前分支**，最後**透過 Gitea API 發 PR**。
+五階段 skill：先執行 **git 同步**（`git fetch` → `git pull`，必要時告知並嘗試解衝突），再**逐條修掉** `.gitea/ai-review/findings.json` 裡的問題並清空該檔，接著把工作區所有變更**依 conventional commit 類型分門別類 commit**，然後 **push 當前分支**，最後**透過 Gitea API 發 PR**。
 
 | 階段 | 動作 |
 | --- | --- |
-| A. 解決問題 | 讀 `findings.json` → 依等級 🔴→🟠→🟡→🔵 逐條修復程式碼 → 清空 `findings.json` 為 `[]` |
+| A. Git 同步 | `git fetch` → `git pull` → 若有衝突則告知並嘗試解衝突 |
-| B. 分類提交 | 分析工作區所有變更 → 依 feat/fix/docs/style/refactor/perf/test/chore/revert 分組 → 各組一個 commit |
+| B. 解決問題 | 讀 `findings.json` → 依等級 🔴→🟠→🟡→🔵 逐條修復程式碼 → 清空 `findings.json` 為 `[]` |
-| C. Push 當前分支 | 認證管理器 → 失敗改 token → 再失敗詢問使用者 |
+| C. 分類提交 | 分析工作區所有變更 → 依 feat/fix/docs/style/refactor/perf/test/chore/revert 分組 → 各組一個 commit |
-| D. 發出 PR | 確定目標分支（不明必問）→ 選 PR 描述（完整／簡單／自訂）→ token 呼叫 Gitea API 建 PR → 通知並清除內文 |
+| D. Push 當前分支 | 認證管理器 → 失敗改 token → 再失敗詢問使用者 |
+| E. 發出 PR | 確定目標分支（不明必問）→ 選 PR 描述（完整／簡單／自訂）→ token 呼叫 Gitea API 建 PR → 通知並清除內文 |
 
 ---
 
@@ -27,7 +28,7 @@ argument-hint: "[--findings <findings.json 路徑>] [--target <目標分支>] [-
   - **PR body**：以 UTF-8 JSON 經 API 送出（如 `--data @body.json`，該檔為 UTF-8 無 BOM）。
   - **送出前自我檢查**：產生含繁中的檔案／訊息後，回頭確認沒有亂碼或 BOM 再提交／送出。
 - **修改程式碼、commit、push、開 PR 屬於更動專案／對外行為**：除非帶 `--yes` 或使用者已明確授權，**否則每階段動手前先輸出計畫（預覽）並取得同意**；使用者拒絕則只輸出計畫、不動檔不提交不推送。
-- **Token 機密保護（極重要）**：gitea token 一律**從環境變數讀取**（如 `$GITEA_TOKEN`），**絕不**寫死在 skill、commit、PR 內文或任何輸出；**不可** echo 含 token 的指令或 URL、不可寫進 log。所有顯示給使用者的指令／錯誤訊息都要**遮蔽 token**（如以 `***` 取代）。階段 D 完成後依規範清除對話內文（見 D5）。
+- **Token 機密保護（極重要）**：gitea token 一律**從環境變數讀取**（如 `$GITEA_TOKEN`），**絕不**寫死在 skill、commit、PR 內文或任何輸出；**不可** echo 含 token 的指令或 URL、不可寫進 log。所有顯示給使用者的指令／錯誤訊息都要**遮蔽 token**（如以 `***` 取代）。階段 E 完成後依規範清除對話內文（見 E6）。
 
 ---
 
@@ -36,17 +37,62 @@ argument-hint: "[--findings <findings.json 路徑>] [--target <目標分支>] [-
 格式：`[--findings <路徑>] [--target <目標分支>] [--pr-desc <full|simple|自訂文字>] [--no-commit] [--no-pr] [--yes]`
 
 - `--findings <路徑>`：findings 檔路徑。**省略時預設 `.gitea/ai-review/findings.json`**（相對於工作目錄根）。
-- `--target <目標分支>`：PR 的目標分支。**省略時於階段 D 必須詢問使用者，不可猜測**。
+- `--target <目標分支>`：PR 的目標分支。**省略時必須詢問使用者，不可猜測**；若需要避免把同名來源分支誤推到目標分支，可能會在階段 D 先詢問並於階段 E 沿用。
-- `--pr-desc <full|simple|自訂文字>`：PR 描述形式。`full`＝完整版（重新分析 diff 總結）、`simple`＝簡單版（逐條列 commit 訊息）、或直接給自訂文字；省略則於階段 D 詢問。
+- `--pr-desc <full|simple|自訂文字>`：PR 描述形式。`full`＝完整版（重新分析 diff 總結）、`simple`＝簡單版（逐條列 commit 訊息）、或直接給自訂文字；省略則於階段 E 詢問。
-- `--no-commit`：只做階段 A（修復 + 清空 findings），**不**執行階段 B/C/D（不提交、不推送、不開 PR）。
+- `--no-commit`：只做階段 A/B（git 同步 + 修復 + 清空 findings），**不**執行階段 C/D/E（不提交、不推送、不開 PR）。
-- `--no-pr`：執行到階段 C（push）為止，**不**開 PR（階段 D 略過）。
+- `--no-pr`：執行到階段 D（push）為止，**不**開 PR（階段 E 略過）。
 - `--yes`：略過各階段的同意確認，直接執行（修復、清空、commit、push、開 PR 一氣呵成）。未帶時每階段先預覽再確認。
 
 ---
 
-## 階段 A：依嚴重等級逐條解決問題
+## 階段 A：Git 同步
 
-### A1. 讀取 findings
+### A1. 檢查同步前狀態
+
+執行同步前先盤點目前分支與工作區狀態：
+
+```bash
+git rev-parse --abbrev-ref HEAD
+git status --porcelain
+```
+
+- **若工作區已有未提交變更**：先告知使用者同步可能需要 merge / rebase 並可能與本地變更衝突；未帶 `--yes` 時先取得同意再繼續。
+- **若目前不在一般分支上**（例如 detached HEAD）：回報狀態並停止，請使用者切到要處理的分支後再執行。
+
+### A2. Fetch 遠端更新
+
+```bash
+git fetch --all --prune
+```
+
+- fetch 失敗時回報錯誤並停止，不進入 findings 修復。
+- 若錯誤訊息可能含 credential / token，輸出前必須遮蔽。
+
+### A3. Pull 當前分支
+
+```bash
+git pull
+```
+
+- pull 成功後進入階段 B。
+- 若顯示需要指定 merge / rebase 策略，先回報原因；未帶 `--yes` 時詢問使用者要採用哪種策略，不可自行猜測。
+- 若 pull 產生衝突，立即告知使用者發生衝突，接著依階段 A4 嘗試解衝突。
+
+### A4. 必要時嘗試解衝突
+
+當 `git pull` 後出現衝突：
+
+1. 用 `git status --porcelain` 與衝突標記定位衝突檔。
+2. 讀取衝突檔脈絡，依專案現有行為與遠端變更做最小合理整合。
+3. 可安全解決的衝突：編輯檔案移除衝突標記，執行 `git add -- <檔案...>` 標記已解決。
+4. 無法安全判斷的衝突：停止處理，列出檔案、衝突原因與需要使用者決策的點；不要硬選任一邊。
+5. 全部衝突解完後，依 git 當前狀態完成 merge / rebase 的必要步驟，確認 `git status --porcelain` 沒有未解衝突，再進入階段 B。
+
+---
+
+## 階段 B：依嚴重等級逐條解決問題
+
+### B1. 讀取 findings
 
 讀 `--findings` 指定（或預設 `.gitea/ai-review/findings.json`）的檔案，內容為 **top-level JSON 陣列**，每筆是一個問題物件。常見欄位（不同產生器命名略有差異，需容錯對應）：
 
@@ -59,15 +105,15 @@ argument-hint: "[--findings <findings.json 路徑>] [--target <目標分支>] [-
 | 問題描述 | `description` / `detail` / `描述` |
 | 修正建議 | `suggestion` / `fix` / `建議` |
 
-- **檔案不存在、內容為 `[]` 或空白** → 視為「無問題待解決」，輸出告知並**直接跳到階段 B**（仍會把工作區既有變更分類提交，除非 `--no-commit`）。
+- **檔案不存在、內容為 `[]` 或空白** → 視為「無問題待解決」，輸出告知並**直接跳到階段 C**（仍會把工作區既有變更分類提交，除非 `--no-commit`）。
 - **JSON 解析失敗** → 回報錯誤與檔案路徑並停止，不臆測內容、不亂改檔。
 
-### A2. 依嚴重等級排序
+### B2. 依嚴重等級排序
 
 把所有 finding 依等級由高到低排序：**🔴 嚴重 → 🟠 高 → 🟡 中 → 🔵 低**。
 英文／其他寫法對應：`critical`/`blocker`→🔴、`high`/`major`→🟠、`medium`/`moderate`→🟡、`low`/`minor`/`info`→🔵；無法辨識的等級**排在最後**並標註「等級未知」。
 
-### A3. 逐條修復（高等級先）
+### B3. 逐條修復（高等級先）
 
 輸出一張「修復計畫」表並（未帶 `--yes` 時）請使用者確認後，**依排序由上而下逐條**處理：
 
@@ -83,7 +129,7 @@ argument-hint: "[--findings <findings.json 路徑>] [--target <目標分支>] [-
 
 > 一次只處理一條、修完再處理下一條，避免互相干擾；同檔多條問題可合併讀取但仍逐條套用修正。
 
-### A4. 清空 findings.json
+### B4. 清空 findings.json
 
 **所有可修復條目處理完畢後**，把 `findings.json` 內容覆寫為**空陣列**：
 
@@ -96,9 +142,9 @@ argument-hint: "[--findings <findings.json 路徑>] [--target <目標分支>] [-
 
 ---
 
-## 階段 B：分析變更並分類提交（`--no-commit` 時略過）
+## 階段 C：分析變更並分類提交（`--no-commit` 時略過）
 
-### B1. 盤點工作區變更
+### C1. 盤點工作區變更
 
 ```bash
 git status --porcelain
@@ -108,14 +154,14 @@ git diff --staged   # 已暫存變更
 
 涵蓋**所有**變更：已修改、新增（未追蹤）、刪除、改名。**無任何變更** → 回報「工作區無變更可提交」並結束。
 
-### B2. 依異動內容歸類 conventional commit 類型
+### C2. 依異動內容歸類 conventional commit 類型
 
 逐一檢視每個變更檔的**實際異動內容**（不只看路徑），歸入下列其一：
 
 | type | 適用情境 |
 | --- | --- |
 | `feat` | 新增功能／新行為／新 API／新 skill |
-| `fix` | 修正錯誤、修掉 bug（**階段 A 的 bug 修復多半歸此**） |
+| `fix` | 修正錯誤、修掉 bug（**階段 B 的 bug 修復多半歸此**） |
 | `docs` | 只改文件（README、註解、`*.md`、說明） |
 | `style` | 不影響邏輯的格式調整（排版、空白、分號、命名一致化） |
 | `refactor` | 重構：不改外部行為的內部結構調整 |
@@ -125,9 +171,9 @@ git diff --staged   # 已暫存變更
 | `revert` | 還原先前的提交 |
 
 - **同一檔案橫跨多型** → 以該檔**主要異動性質**歸類；難以拆分時就近歸入影響最大的一類，並在總結註記。
-- **階段 A 修復產生的變更**：依其性質歸類（修 bug→`fix`、補功能→`feat`、改文件→`docs`…）。`findings.json` 被清空這項異動歸 `chore`。
+- **階段 B 修復產生的變更**：依其性質歸類（修 bug→`fix`、補功能→`feat`、改文件→`docs`…）。`findings.json` 被清空這項異動歸 `chore`。
 
-### B3. 產出提交計畫並確認
+### C3. 產出提交計畫並確認
 
 把變更檔依 type 分組，**每個 type 一個 commit**，輸出提交計畫供確認（未帶 `--yes` 時）：
 
@@ -145,7 +191,7 @@ git diff --staged   # 已暫存變更
   - 範例：`feat(使用者登入): 新增帳密登入與 token 簽發`、`fix(結帳流程): 修正空購物車導致的結帳例外`、`perf(物件查詢): 改用批次查詢降低 DB 往返`、`docs(README): 補上安裝與呼叫方式說明`、`chore(plugin 版本): bump 至 0.0.8 並清空 findings.json`。
 - **提交順序建議**：`fix`/`feat` 等核心異動在前，`docs`/`style`/`chore` 在後（純屬建議，可依相依性調整）。
 
-### B4. 執行分類提交
+### C4. 執行分類提交
 
 對每組依序：
 
@@ -156,14 +202,25 @@ git commit -m "type(範圍): 一句總結"   # 範圍＝實際異動的功能／
 
 - **逐組 add／commit**，確保每個 commit 只含該類異動；不要一次 `git add -A` 再混在一起。
 - 改名／刪除檔一併納入對應組的 `git add`（`git add -A -- <路徑>` 或明確列出）。
-- commit 完成後進入階段 C（push）；`--no-commit` 或無新 commit 時不進入後續階段。
+- commit 完成後進入階段 D（push）；`--no-commit` 或無新 commit 時不進入後續階段。
 
 ---
 
-## 階段 C：Push 當前分支（`--no-commit`／無新 commit 時略過）
+## 階段 D：Push 當前分支（`--no-commit`／無新 commit 時略過）
 
 commit 完成後推送**當前分支**，依序嘗試三種方式，前者失敗才退到下一個：
 
+推送前先記錄目前來源分支與其遠端基準：
+
+```bash
+source_branch="$(git rev-parse --abbrev-ref HEAD)"
+git rev-parse --verify "origin/${source_branch}"
+```
+
+- 若來源分支沒有對應的 `origin/<source_branch>`，先記錄「無遠端基準」並繼續；後續若 source/base 同名，階段 E2 仍必須以 `origin/<target>` 作為帶入 commit 的比較基準。
+- 若後續會建立 PR（未帶 `--no-pr`）且尚未知道目標分支，先依階段 E1 的規則詢問目標分支，避免把 commit 直接推進目標分支後才發現 source/base 相同。
+- 若來源分支名稱與目標分支相同，**不要 push 原來源分支**；記下來源分支與遠端基準，直接進入階段 E，由 E2 建立新的 PR 來源分支、帶入 commit 後再 push 新分支。
+
 1. **認證管理器（優先）**：直接用 git 既有的 credential helper（如 Windows 的 `manager-core`）：
 
    ```bash
@@ -182,30 +239,72 @@ commit 完成後推送**當前分支**，依序嘗試三種方式，前者失敗
 
 3. **再失敗 → 詢問使用者要如何 push**：列出失敗原因（遮蔽 token），請使用者指示推送方式，**不可自行猜測**其他憑證或來源。
 
-push 成功後記下遠端分支名，進入階段 D。
+push 成功後記下遠端分支名，進入階段 E。若因來源分支與目標分支相同而延後 push，記下原因並進入階段 E2 建立新分支。
 
 ---
 
-## 階段 D：透過 Gitea API 發出 PR（`--no-pr`／`--no-commit` 時略過）
+## 階段 E：透過 Gitea API 發出 PR（`--no-pr`／`--no-commit` 時略過）
 
-### D1. 確定目標分支（不可猜想）
+### E1. 確定目標分支（不可猜想）
 
 - 帶 `--target <分支>` → 直接採用。
+- 若階段 D 已為了避免 source/base 相同而詢問過目標分支，沿用該目標分支。
 - **否則必須詢問使用者目標分支**（可用 `git branch -r` 列出輔助選擇），**嚴禁臆測或預設**（不可自行假設 develop／main／master）。
 
-### D2. 解析 repo 座標
+### E2. 若來源分支與目標分支相同，改建 PR 來源分支
+
+先取得目前 PR 來源分支：
+
+```bash
+git rev-parse --abbrev-ref HEAD
+```
+
+若來源分支名稱與 `--target` 指定（或使用者選定）的目標分支相同，**不可直接建立 head=base 的 PR，也不可先把原來源分支 push 到目標分支**。改用下列流程建立新的 PR 來源分支，並把原來源分支的 commit 帶入後再開 PR：
+
+1. 先記錄原來源分支名稱與要帶入的 commit 清單：
+
+   ```bash
+   source_branch="$(git rev-parse --abbrev-ref HEAD)"
+   git log --oneline "origin/${target}..${source_branch}"
+   ```
+
+   - 若 `origin/<target>` 不存在，先回報並停止，不猜測替代 base。
+   - 若沒有任何 commit 可帶入，回報「來源分支沒有領先目標分支的 commit」，停止開 PR。
+   - 若階段 D 已記錄來源分支的遠端基準，使用該基準判斷要帶入的 commit，避免把原來源分支直接推進目標分支。
+
+2. 從目標分支的遠端基準建立新分支。新分支名稱需可讀且避免覆蓋既有分支，例如：
+
+   ```bash
+   git switch -c "ai-review-resolve/<短時間戳>" "origin/${target}"
+   ```
+
+3. 將原來源分支領先目標分支的 commit 依序帶入新分支：
+
+   ```bash
+   git cherry-pick "origin/${target}..${source_branch}"
+   ```
+
+   - cherry-pick 發生衝突時，先告知使用者，再依專案脈絡嘗試最小合理解衝突。
+   - 可安全解決的衝突：移除衝突標記、`git add -- <檔案...>`，再繼續 `git cherry-pick --continue`。
+   - 無法安全判斷的衝突：停止處理，列出衝突檔案與需要使用者決策的點；不要硬選任一邊。
+
+4. 將新分支 push 到遠端，使用階段 D 的同一套 push 憑證策略，並把後續 PR 的 `head` 改為這個新分支。
+
+若來源分支與目標分支不同，直接以目前分支作為 PR 的 `head`。
+
+### E3. 解析 repo 座標
 
 從 `git remote get-url origin` 解析出 **host／owner／repo**（例：`https://gitea.jsc.idv.tw/plugins/code-review.git` → host=`gitea.jsc.idv.tw`、owner=`plugins`、repo=`code-review`）。
 
-### D3. 決定 PR 描述形式（完整版／簡單版／使用者輸入）
+### E4. 決定 PR 描述形式（完整版／簡單版／使用者輸入）
 
 依 `--pr-desc`（或詢問）三選一：
 
-- **完整版（`full`）**：**重新分析並總結** `git diff <target>...<當前分支>`（比對 source 自分岔點以來的變更），整理成結構化繁體中文說明 —— 變更摘要、影響範圍、重點檔案／模組、風險或注意事項。不是貼原始 diff，而是「人讀得懂的總結」。
+- **完整版（`full`）**：**重新分析並總結** `git diff <target>...<PR 來源分支>`（比對 source 自分岔點以來的變更），整理成結構化繁體中文說明 —— 變更摘要、影響範圍、重點檔案／模組、風險或注意事項。不是貼原始 diff，而是「人讀得懂的總結」。
 - **簡單版（`simple`）**：直接把本分支領先 target 的 commit 訊息**逐條列出**：
 
   ```bash
-  git log --oneline "<target>..$(git rev-parse --abbrev-ref HEAD)"
+  git log --oneline "<target>..<PR 來源分支>"
   ```
 
   以條列呈現每行 commit 訊息。
@@ -213,7 +312,7 @@ push 成功後記下遠端分支名，進入階段 D。
 
 PR **標題**預設取一句總結（可用首個 feat/fix commit 或分支用途）；使用者另有指定則從之。
 
-### D4. 呼叫 Gitea API 建立 PR（使用 token）
+### E5. 呼叫 Gitea API 建立 PR（使用 token）
 
 token 從環境變數讀取，呼叫 Gitea 建立 PR：
 
@@ -223,13 +322,13 @@ curl -sS -X POST \
   -H "Authorization: token ${GITEA_TOKEN}" \
   -H "Content-Type: application/json" \
   "https://<host>/api/v1/repos/<owner>/<repo>/pulls" \
-  -d '{"head":"<當前分支>","base":"<target>","title":"<標題>","body":"<描述>"}'
+  -d '{"head":"<PR 來源分支>","base":"<target>","title":"<標題>","body":"<描述>"}'
 ```
 
 - **成功**：取回應中的 PR 連結／編號回報使用者。
 - **失敗**：顯示 API 回應的錯誤訊息供排查（**先遮蔽 token**）。常見錯誤：目標分支不存在、已有相同 head→base 的 PR、token 權限不足。
 
-### D5. 完成通知 + 清除對話內文（重要：可能含 token）
+### E6. 完成通知 + 清除對話內文（重要：可能含 token）
 
 1. **通知使用者**：push 結果、PR 連結／編號、PR 描述採用哪種形式。
 2. **清除 AI 助理對話內文**：因為 push／API 過程可能使對話內文殘留 gitea token，**完成後務必清除對話內文／上下文**以免外洩：
@@ -243,10 +342,11 @@ curl -sS -X POST \
 
 各階段執行後輸出：
 
-- **階段 A**：已修復 N 條（依等級分佈）、待人工處理 M 條（列出原因）、findings.json 是否已清空。
+- **階段 A**：git fetch / pull 是否成功、是否發生衝突、衝突是否已解決或仍需人工處理。
-- **階段 B**：建立了哪幾個 commit（type＋訊息＋檔數），或為何略過（`--no-commit` / 無變更）。
+- **階段 B**：已修復 N 條（依等級分佈）、待人工處理 M 條（列出原因）、findings.json 是否已清空。
-- **階段 C**：push 成功與否、用了哪種方式（認證管理器／token／使用者指定），遠端分支名。
+- **階段 C**：建立了哪幾個 commit（type＋訊息＋檔數），或為何略過（`--no-commit` / 無變更）。
-- **階段 D**：PR 連結／編號、目標分支、描述形式；並提醒已（或請使用者）清除對話內文以防 token 外洩。
+- **階段 D**：push 成功與否、用了哪種方式（認證管理器／token／使用者指定），遠端分支名。
+- **階段 E**：PR 連結／編號、目標分支、描述形式；並提醒已（或請使用者）清除對話內文以防 token 外洩。
 
 ---