skills/code-review-resolve/SKILL.md

@@ -1,17 +1,17 @@
 ---
 name: code-review-resolve
-description: 解決 `.gitea/ai-review/findings.json` 的 AI review findings，先同步 git（fetch → 檢查目前分支的遠端分支是否存在；存在則留在目前分支 pull 更新，不存在則切換到 develop／master 後 pull 更新；只有來源分支與 PR 目標分支相同時才建立新的工作分支；必要時嘗試解衝突），再依嚴重度逐條修復；可判斷為誤報者寫入 `.gitea/ai-review/exclusions.json`，已解決或已登記為誤報的 finding 可自 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`（不存在或空時 fallback 讀 `.gitea/ai-review/findings/` 目錄下 `*.json`）的 AI review findings，先同步 git（fetch → 檢查目前分支的遠端分支是否存在；存在則留在目前分支 pull 更新，不存在則切換到 develop／master 後 pull 更新；只有來源分支與 PR 目標分支相同時才建立新的工作分支；必要時嘗試解衝突），再依嚴重度逐條修復；可判斷為誤報者寫入 `.gitea/ai-review/exclusions.json`，已解決或已登記為誤報的 finding 可自 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：先執行 **git 同步**（`git fetch` → 確認目前分支的遠端分支是否存在；存在則留在目前分支 `git pull` 更新，不存在則切換到 `develop`，再退而 `master` 後 `git pull` 更新；只有來源分支與 PR 目標分支相同時才建立新的工作分支；必要時告知並嘗試解衝突），再**逐條處理** `.gitea/ai-review/findings.json` 裡的問題；成立問題修復後自 findings 移除，可判斷為誤報者寫入 `.gitea/ai-review/exclusions.json` 後也可自 findings 移除，接著**必須盤點並處理工作區的所有變更**，再依 conventional commit 類型分門別類 commit，然後 **push 當前分支**，最後**透過 Gitea API 發 PR**。
+五階段 skill：先執行 **git 同步**（`git fetch` → 確認目前分支的遠端分支是否存在；存在則留在目前分支 `git pull` 更新，不存在則切換到 `develop`，再退而 `master` 後 `git pull` 更新；只有來源分支與 PR 目標分支相同時才建立新的工作分支；必要時告知並嘗試解衝突），再**逐條處理** `.gitea/ai-review/findings.json`（不存在或空時 fallback 讀 `.gitea/ai-review/findings/` 目錄下所有 `*.json`）裡的問題；成立問題修復後自 findings 移除，可判斷為誤報者寫入 `.gitea/ai-review/exclusions.json` 後也可自 findings 移除，接著**必須盤點並處理工作區的所有變更**，再依 conventional commit 類型分門別類 commit，然後 **push 當前分支**，最後**透過 Gitea API 發 PR**。
 
 | 階段 | 動作 |
 | --- | --- |
 | A. Git 同步 | `git fetch` → 當前分支不在遠端則切換 develop（再退而 master）→ `git pull`／必要時解衝突 → 只有來源分支與 PR 目標分支相同時才建立新工作分支 |
-| B. 解決問題 | 讀 `findings.json` / `exclusions.json` → 依等級 🔴→🟠→🟡→🔵 逐條修復或判斷誤報 → 已解決者自 `findings.json` 移除，誤報寫入 `exclusions.json` 後也可移除；**無待處理問題則跳到階段 D** |
+| B. 解決問題 | 讀 `findings.json`（不存在或空則 fallback `findings/*.json`）/ `exclusions.json` → 依等級 🔴→🟠→🟡→🔵 逐條修復或判斷誤報 → 已解決者自 `findings.json` 移除，誤報寫入 `exclusions.json` 後也可移除；**無待處理問題則跳到階段 D** |
 | C. 分類提交 | 必須分析並涵蓋工作區所有變更（已修改／新增／刪除／改名，含已暫存與未暫存、未追蹤檔、findings/exclusions 更新）→ 依 feat/fix/docs/style/refactor/perf/test/chore/revert 分組 → 各組一個 commit |
 | D. Push 當前分支 | 認證管理器 → 失敗改 token → 再失敗詢問使用者；**無 commit 可 push 則跳到階段 E** |
 | E. 發出 PR | 確定目標分支（不明必問）→ 選 PR 描述（完整／簡單／自訂）→ token 呼叫 Gitea API 建 PR → 通知並清除內文 |
@@ -39,7 +39,7 @@ argument-hint: "[--findings <findings.json 路徑>] [--target <目標分支>] [-
 
 格式：`[--findings <路徑>] [--target <目標分支>] [--pr-desc <full|simple|自訂文字>] [--no-commit] [--no-pr] [--yes]`
 
-- `--findings <路徑>`：findings 檔路徑。**省略時預設 `.gitea/ai-review/findings.json`**（相對於工作目錄根）。
+- `--findings <路徑>`：findings 檔路徑。**省略時預設先讀 `.gitea/ai-review/findings.json`；該檔不存在或為空時，fallback 改讀目錄 `.gitea/ai-review/findings/` 下所有 `*.json` 並合併**（相對於工作目錄根）。指定路徑（檔案或目錄）時直接採用，不套用 fallback。
 - `--target <目標分支>`：PR 的目標分支。**省略時必須詢問使用者，不可猜測**；若需要避免把同名來源分支誤推到目標分支，可能會在階段 D 先詢問並於階段 E 沿用。
 - `--pr-desc <full|simple|自訂文字>`：PR 描述形式。`full`＝完整版（重新分析 diff 總結）、`simple`＝簡單版（逐條列 commit 訊息）、或直接給自訂文字；省略時預設 `full`，不要為描述形式中斷詢問。
 - `--no-commit`：只做階段 A/B（git 同步 + 修復 + 更新 findings/exclusions），**不**執行階段 C/D/E（不提交、不推送、不開 PR）。
@@ -143,7 +143,14 @@ source_branch="$(git rev-parse --abbrev-ref HEAD)"
 
 ### B1. 讀取 findings 與 exclusions
 
-讀 `--findings` 指定（或預設 `.gitea/ai-review/findings.json`）的檔案，內容為 **top-level JSON 陣列**，每筆是一個問題物件。常見欄位（不同產生器命名略有差異，需容錯對應）：
+**B1-0. 定位 findings 來源**（依序判斷，決定要讀哪些 finding 檔）：
+
+1. **省略 `--findings` 時**：先讀預設 `.gitea/ai-review/findings.json`。
+2. **若 `findings.json` 不存在，或內容為 `[]`／空白／僅空白字元** → fallback 到目錄 `.gitea/ai-review/findings/`：讀取該目錄（含子目錄）下所有 `*.json`，依檔名排序後合併；每個檔各自為 **top-level JSON 陣列**（若為單一 finding 物件則容錯包成單元素陣列）。
+3. **合併時逐筆記住各 finding 的來源檔路徑**，供階段 B4 逐檔就地寫回；此步驟不得更動任何來源檔。
+4. **指定 `--findings <路徑>` 時**：直接採用該路徑，不套用上述 fallback。指定的是檔案就讀該檔；指定的是目錄則比照第 2 點合併該目錄下所有 `*.json`。
+
+無論來源是單一 `findings.json` 或目錄下多個 `*.json`，內容皆為 **top-level JSON 陣列**，每筆是一個問題物件。常見欄位（不同產生器命名略有差異，需容錯對應）：
 
 | 語義 | 可能欄位名 |
 | --- | --- |
@@ -181,7 +188,7 @@ source_branch="$(git rev-parse --abbrev-ref HEAD)"
 
   若既有 exclusions 使用 `suggestion`、`title`、`note` 等欄位，讀取時可容錯；寫回時仍要維持 top-level array，並盡量採用上述 canonical 欄位。
 
-- **檔案不存在、內容為 `[]` 或空白** → 視為「無問題待解決」，輸出告知。`--no-commit` 時就此結束；否則**跳過階段 C 直接進入階段 D**（無待處理問題代表本 skill 未產生需要分類提交的修復變更）。
+- **`findings.json` 與 `.gitea/ai-review/findings/` 目錄皆無可處理的 finding**（依 B1-0 判定：檔案不存在、內容為 `[]` 或空白，且 fallback 目錄不存在／無 `*.json`／全部為空陣列）→ 視為「無問題待解決」，輸出告知。`--no-commit` 時就此結束；否則**跳過階段 C 直接進入階段 D**（無待處理問題代表本 skill 未產生需要分類提交的修復變更）。
 - **JSON 解析失敗** → 回報錯誤與檔案路徑並停止，不臆測內容、不亂改檔。
 - `exclusions.json` 不存在時視為空陣列，必要時建立 `.gitea/ai-review/exclusions.json` 並寫入 `[]` 或新增後的排除項目。
 - 若 `exclusions.json` 是舊 wrapper 格式（例如 `{ "exclusions": [...] }` 或 `{ "excluded_findings": [...] }`），先正規化為 top-level array 再寫回。
@@ -224,6 +231,8 @@ canonical 等級為 `critical` / `warning` / `info`；其他寫法容錯對應
 ```
 
 - 寫回 `findings.json` 時保留未解決 finding 的 canonical 欄位（`level`、`role`、`location`、`suggestion`）與有用原欄位；依嚴重度排序。
+- **來源為目錄 `.gitea/ai-review/findings/` 時（逐檔就地更新）**：依 B1-0 記錄的來源檔，把尚未解決且尚未登記為誤報的 finding 寫回**其原本所屬檔案**，不得合併到單一 `findings.json`；某來源檔的 finding 全部已解決／誤報時，將**該檔**寫成空陣列 `[]`（保留檔案、維持目錄結構，不刪檔）。上述保留欄位、排序、UTF-8 規範對每個來源檔一體適用。
+- 誤報一律統一寫入 `.gitea/ai-review/exclusions.json`（不因來源是目錄而分檔）。
 - 寫回 `exclusions.json` 時使用 top-level JSON array；新增項目 append 後依既有順序保留並去重。
 - 兩個檔案都以 UTF-8（不含 BOM）寫入，結尾保留一個換行。
 
@@ -259,7 +268,7 @@ git ls-files --others --exclude-standard   # 未追蹤檔
 | `revert` | 還原先前的提交 |
 
 - **同一檔案橫跨多型** → 以該檔**主要異動性質**歸類；難以拆分時就近歸入影響最大的一類，並在總結註記。
-- **階段 B 修復產生的變更**：依其性質歸類（修 bug→`fix`、補功能→`feat`、改文件→`docs`…）。`findings.json` / `exclusions.json` 的問題狀態更新歸 `chore`。
+- **階段 B 修復產生的變更**：依其性質歸類（修 bug→`fix`、補功能→`feat`、改文件→`docs`…）。`findings.json`（或 `findings/` 目錄下 `*.json`）／ `exclusions.json` 的問題狀態更新歸 `chore`。
 - **未追蹤新檔**：必須照實際內容歸入對應 type，必要時在提交前明確 `git add -- <path>`，不可因為是新檔就略過。
 
 ### C3. 產出提交計畫
@@ -450,7 +459,7 @@ curl -sS -X POST \
 ## 呼叫方式
 
 格式：`[--findings <路徑>] [--target <目標分支>] [--pr-desc <full|simple|自訂文字>] [--no-commit] [--no-pr] [--yes]` —
-全部可省略（findings 預設 `.gitea/ai-review/findings.json`；目標分支省略時必問、不猜測）。token 一律由環境變數（如 `GITEA_TOKEN`）提供。
+全部可省略（findings 預設 `.gitea/ai-review/findings.json`，不存在或空時 fallback 目錄 `.gitea/ai-review/findings/`；目標分支省略時必問、不猜測）。token 一律由環境變數（如 `GITEA_TOKEN`）提供。
 
 | 助理 | 呼叫 |
 | --- | --- |