code-review/skills/archive-findings/SKILL.md

name, description, argument-hint

name	description	argument-hint
archive-findings	將 /jsc:code-review 已裁決的問題保存到目標專案 —【✅ 成立】附加到「前次審查紀錄（已知問題）」檔、【❌ 誤判】附加到「排除事項」檔，讓 code-review 防守方下次自動標為 🔁 已知問題 / 🚫 略過。當使用者說保存／歸檔 code review 結果、把成立問題寫進已知問題、把誤判寫進排除事項、把 review 裁決落地到專案時觸發。只處理「已裁決」的列表（合併防守方裁決表與攻擊方問題表），不自己跑 review、不修改程式碼。缺裁決表時，請先用 /jsc:code-review 的防守方（paladin）產生裁決。	--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（.md）

目標檔不存在時先建立標題：

• 已知問題檔：# 前次審查紀錄（已知問題）\n\n由 /jsc:archive-findings 從 code-review【✅ 成立】問題彙整；/jsc:code-review 防守方會讀此檔並標「🔁 已知問題」。
• 排除事項檔（.codereview.md）：# Code Review 排除事項\n\n已知技術債／團隊慣例／刻意取捨／已確認的誤判；/jsc:code-review 防守方會讀此檔並標「🚫 略過」。

已知問題 每筆：

### [<等級>] <問題標題>
<!-- key: <檔案位置>|<問題標題> -->
- 檔案：`<檔案位置>:<所在行數>`
- 描述：<描述>
- 建議：<最終建議>
- 裁決：✅ 成立（<理由>）— 由 <來源角色> 提出
- 範圍：`<target>...<source>`，<日期>

排除事項 每筆：

### <問題標題>
<!-- key: <檔案位置>|<問題標題> -->
- 檔案：`<檔案位置>`
- 排除原因（❌ 誤判）：<裁決理由>
- 範圍：`<target>...<source>`，<日期>

JSON（.json）

維持 top-level array（不要包在物件裡）；每筆一個物件，以 key 去重：

{
  "key": "<檔案位置>|<問題標題>",
  "title": "<問題標題>",
  "severity": "🔴 嚴重 | 🟠 高 | 🟡 中 | 🔵 低",
  "file": "<檔案位置>",
  "line": "<所在行數>",
  "description": "<描述>",
  "suggestion": "<最終建議>",
  "verdict": "成立 | 誤判",
  "reason": "<理由>",
  "source": "<target>...<source>",
  "date": "YYYY-MM-DD"
}

---

模板（空檔／新檔的初始內容）

目標檔不存在或為空時，先寫入下列模板（同一份也隨附於本 skill 的 templates/），再於對應標題下附加條目。

已知問題檔（--known-issues，.md）

# 前次審查紀錄（已知問題 / Known Issues）

> 本檔由 `/jsc:archive-findings` 自動維護，記錄 `/jsc:code-review` 防守方裁定 **✅ 成立** 但尚未解決的問題。
> `/jsc:code-review` 防守方在步驟 3(b) 會讀此檔：若新發現與此處條目相符，標為 **🔁 已知問題（前次未解決）**，不重複裁決。
> 問題修復後請刪除對應條目。每筆以 `<!-- key: 檔案位置|問題標題 -->` 去重。

## 待解決問題

<!-- archive-findings 由此往下追加條目；條目格式見 /jsc:archive-findings 說明。 -->

排除事項檔（--exclusions，.md）

# Code Review 排除事項（Exclusions）

> 本檔由 `/jsc:archive-findings` 維護（也可手動編輯），列出已知技術債／團隊慣例／刻意取捨／已確認的誤判。
> `/jsc:code-review` 防守方在步驟 3(a) 會讀此檔：若新發現命中此處條目，標為 **🚫 略過（排除事項）**，不再裁決。
> 不再適用時請手動移除。每筆以 `<!-- key: 檔案位置|問題標題 -->` 去重。

## 排除項目

<!-- archive-findings 由此往下追加條目；條目格式見 /jsc:archive-findings 說明。 -->

JSON（.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」）自動觸發