@@ -0,0 +1,169 @@
---
name : archive-findings
description : 將 /jsc:code-review 已裁決的問題保存到目標專案 —【✅ 成立】附加到「前次審查紀錄（已知問題）」檔、【❌ 誤判】附加到「排除事項」檔，讓 code-review 防守方下次自動標為 🔁 已知問題 / 🚫 略過。當使用者說保存／歸檔 code review 結果、把成立問題寫進已知問題、把誤判寫進排除事項、把 review 裁決落地到專案時觸發。只處理「已裁決」的列表（合併防守方裁決表與攻擊方問題表），不自己跑 review、不修改程式碼。缺裁決表時，請先用 /jsc:code-review 的防守方（paladin）產生裁決。
argument-hint : "--known-issues <前次審查紀錄路徑> --exclusions <排除事項檔案路徑>"
---
# archive-findings — 保存 code-review 裁決結果到專案
把 `/jsc:code-review` 防守方的裁決落地成兩份專案紀錄，形成下次審查的回饋圈：
| 裁決 | 動作 |
| --- | --- |
| ✅ 成立 | 附加到**前次審查紀錄（已知問題）檔** → 下次審查會被標 * * 🔁 已知問題** |
| ❌ 誤判 | 附加到**排除事項檔** → 下次審查會被標 * * 🚫 略過** |
| 🔁 已知問題 | 已在已知問題檔，**不重複寫入**（僅計數） |
| 🚫 略過 | 已在排除事項檔，**不重複寫入**（僅計數） |
> 與 `/jsc:code-review` 的關係：code-review 的步驟 7 只會（在同意後）把 ✅ 成立 寫入已知問題檔；
> **誤判 → 排除事項** 它不會寫。本 skill 一次補齊兩個方向，且**只吃既有裁決結果**：不跑 review、不改程式碼。
## 參數（與 code-review 同名旗標，方便沿用同一組路徑）
`--known-issues <前次審查紀錄路徑>` `--exclusions <排除事項檔案路徑>` — **兩者皆必填，一定要指定 ** 。
- **未提供任一路徑 → 必須先向使用者取得，不可自行採用預設或臆測**（與 code-review 一致：預設檔名僅作詢問時的建議選項）。
建議預設：已知問題 `.codereview-known-issues.md` 、排除事項 `.codereview.md` （與 code-review 防守方讀的同一檔）。
- **檔案本身允許不存在或為空內容**：若目標檔不存在、或內容為空（含只有空白）→ skill 先**依模板建立該檔**（見下方「模板」），再附加條目；既有非空檔則直接附加。
- 寫入屬於**更動專案檔案**的行為 → **未獲使用者同意前不可寫入 ** ；拒絕則只輸出將寫入的預覽。
- **格式依副檔名自動決定**： `.md` → Markdown（用下方模板）；`.json` → top-level JSON array（空／不存在時初始化為 `[]` ）。
## 執行流程
### 1. 取得問題表與裁決表（只吃既有結果）
來源優先序：本次對話中上一個 `/jsc:code-review` 的輸出；若無，請使用者貼上。
- **問題表**（攻擊方）：`問題 | 等級 | 描述 | 建議 | 檔案位置 | 所在行數` 。
- **裁決表**（防守方）：`來源角色 | 原問題 | 裁決 | 理由 | 最終建議` ，裁決 ∈ `🚫 略過 / 🔁 已知問題 / ❌ 誤判 / ✅ 成立` 。
- **沒有裁決表** → 無法分類，**請先跑防守方**（`/jsc:code-review <target> <source> paladin` ）或請使用者提供裁決表。
**只處理已裁決的列表 ** ，不自行臆測成立或誤判。
### 2. 合併兩表
以 * * `原問題` ↔ `問題` ** 為鍵配對；同名問題以 * * `來源角色` + `檔案位置` ** 區分。
合併後每筆 = 等級／描述／建議／檔案位置／所在行數（問題表）＋ 裁決／理由／最終建議（裁決表）。
- **對不上的列**（裁決表有但問題表查無，或反之）→ 列出請使用者確認，**不臆測**、不寫入。
### 3. 補齊欄位
- **日期**： `YYYY-MM-DD` （可用 `date +%F` ，或取來源分支最後 commit 日期）。
- **範圍／來源**： `<target>...<source>` （沿用本次 review 的分支；不確定就問或留白）。
### 4. 取得同意 → 去重 → 附加
1. 先輸出「將寫入」的預覽（各檔幾筆、條目摘要），**請使用者確認**後才動檔。
2. **去重鍵 ** ： `<檔案位置>|<問題標題>` 。寫入前先讀目標檔，**已存在相同鍵的條目 → 略過不重複附加**。
3. **目標檔不存在或為空（含只有空白）→ 先依「模板」建立 ** （ `.md` 用下方模板；`.json` 初始化為 `[]` ），再附加。
4. 分流：
- **✅ 成立** → 附加到**已知問題檔**（`--known-issues` ）。
- **❌ 誤判** → 附加到**排除事項檔**（`--exclusions` ）。
- **🔁 已知問題 / 🚫 略過** → 不處理（已存在），僅計數。
### 5. 回報摘要
列出：新增成立 N 筆、新增誤判 M 筆、已知問題（略過）K 筆、排除（略過）L 筆、重複而跳過 J 筆，以及實際寫入的檔案路徑。
---
## 檔案格式
### Markdown（ ）
目標檔不存在時先建立標題：
- 已知問題檔：`# 前次審查紀錄（已知問題）\n\n由 /jsc:archive-findings 從 code-review【✅ 成立】問題彙整；/jsc:code-review 防守方會讀此檔並標「🔁 已知問題」。`
- 排除事項檔（`.codereview.md` ）：`# Code Review 排除事項\n\n已知技術債／團隊慣例／刻意取捨／已確認的誤判；/jsc:code-review 防守方會讀此檔並標「🚫 略過」。`
**已知問題 ** 每筆：
``` markdown
### [<等級>] <問題標題>
<!-- key: <檔案位置>|<問題標題> -->
- 檔案：`<檔案位置>:<所在行數>`
- 描述：<描述>
- 建議：<最終建議>
- 裁決：✅ 成立（<理由>）— 由 <來源角色> 提出
- 範圍：`<target>...<source>` ，
```
**排除事項 ** 每筆：
``` markdown
### <問題標題>
<!-- key: <檔案位置>|<問題標題> -->
- 檔案：`<檔案位置>`
- 排除原因（❌ 誤判）：<裁決理由>
- 範圍：`<target>...<source>` ，
```
### JSON（ ）
維持 **top-level array ** （不要包在物件裡）；每筆一個物件，以 `key` 去重：
``` json
{
"key" : "<檔案位置>|<問題標題>" ,
"title" : "<問題標題>" ,
"severity" : "🔴 嚴重 | 🟠 高 | 🟡 中 | 🔵 低" ,
"file" : "<檔案位置>" ,
"line" : "<所在行數>" ,
"description" : "<描述>" ,
"suggestion" : "<最終建議>" ,
"verdict" : "成立 | 誤判" ,
"reason" : "<理由>" ,
"source" : "<target>...<source>" ,
"date" : "YYYY-MM-DD"
}
```
---
## 模板（空檔／新檔的初始內容）
目標檔不存在或為空時，先寫入下列模板（同一份也隨附於本 skill 的 `templates/` ），再於對應標題下附加條目。
### 已知問題檔（`--known-issues`， ）
``` markdown
# 前次審查紀錄（已知問題 / Known Issues）
> 本檔由 `/jsc:archive-findings` 自動維護，記錄 `/jsc:code-review` 防守方裁定 **✅ 成立** 但尚未解決的問題。
> `/jsc:code-review` 防守方在步驟 3(b) 會讀此檔：若新發現與此處條目相符，標為 **🔁 已知問題（前次未解決）**，不重複裁決。
> 問題修復後請刪除對應條目。每筆以 `<!-- key: 檔案位置|問題標題 -->` 去重。
## 待解決問題
<!-- archive-findings 由此往下追加條目；條目格式見 /jsc:archive-findings 說明。 -->
```
### 排除事項檔（`--exclusions`， ）
``` markdown
# Code Review 排除事項（Exclusions）
> 本檔由 `/jsc:archive-findings` 維護（也可手動編輯），列出已知技術債／團隊慣例／刻意取捨／已確認的誤判。
> `/jsc:code-review` 防守方在步驟 3(a) 會讀此檔：若新發現命中此處條目，標為 **🚫 略過（排除事項）**，不再裁決。
> 不再適用時請手動移除。每筆以 `<!-- key: 檔案位置|問題標題 -->` 去重。
## 排除項目
<!-- archive-findings 由此往下追加條目；條目格式見 /jsc:archive-findings 說明。 -->
```
### JSON（ ）
空／不存在時初始化為空陣列，再 append 物件：`[]`
---
## 呼叫方式
格式：`--known-issues <路徑> --exclusions <路徑>` — **兩者必填 ** ；未提供會反問取得。需先有 `/jsc:code-review` 的問題表＋裁決表。
| 助理 | 呼叫 |
| --- | --- |
| Claude Code / Antigravity | `/jsc:archive-findings --known-issues .codereview-known-issues.md --exclusions .codereview.md` （或省略路徑由它反問） |
| Codex | `$archive-findings --known-issues docs/known-issues.md --exclusions docs/review-rules.md` ，或用 `/skills` 選單 |
| OpenCode | 描述需求（如「把剛剛 code-review 成立的問題存到 .codereview-known-issues.md、誤判存到 .codereview.md」）自動觸發 |