From 51c2705667c52093b31a37df5c0c56ef6693a7d7 Mon Sep 17 00:00:00 2001
From: Jeffery <jiantw83@yahoo.com>
Date: Thu, 27 Aug 2026 15:41:38 +0800
Subject: [PATCH] =?UTF-8?q?feat(review):=20code-review=20=E7=AF=84?=
 =?UTF-8?q?=E5=9C=8D=E6=94=B9=E7=82=BA=205.1=20=E5=88=B0=205.8=20=E4=B8=A6?=
 =?UTF-8?q?=E8=A3=9C=E4=B8=8A=E8=88=87=20api-doc=20=E7=9A=84=E5=88=86?=
 =?UTF-8?q?=E5=B7=A5?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

What：skills/code-review/SKILL.md 的審查範圍表，第 5 組由原本一句
「smells.md group 5」改成明確的 5.1 到 5.8，並點名 5.6、5.7、5.8 三個新項目；
Notes 加一行分工，Swagger 文件稽核歸 api-doc。README.md 新增 api-doc 的技能
小節，另補一張工具表格列出 swagger-detect.sh。

Why：sub agent 讀的是 SKILL.md 的審查範圍表，範圍表沒寫清楚，新增的 5.6 到
5.8 就不會被查。使用者讀的是 README.md，新技能與新工具沒列出來就找不到。
兩支技能都碰註解與文件，界線不寫明就會對同一個缺失重複回報。

How：範圍表的第 5 組直接列出三個新項目與各自的判準重點，完整清單仍指向
references/smells.md。Notes 寫明 api-doc 負責狀態碼的回覆類型、Swagger 參數
說明與範例，第 5 組只負責原始碼註解契約。README.md 的技能小節寫明偵測先行、
只裝套件沒掛接就停手；工具表格列出 swagger-detect.sh 的用途、輸出欄位與結束碼。

Who：jsc-review 的 code-review 技能與存取庫說明文件。
---
 README.md                   | 10 ++++++++++
 skills/code-review/SKILL.md |  3 ++-
 2 files changed, 12 insertions(+), 1 deletion(-)

diff --git a/README.md b/README.md
index 44a199b..4cf69ab 100644
--- a/README.md
+++ b/README.md
@@ -28,6 +28,10 @@ Marketplace 統一為 `jsc`（https://gitea.jsc.idv.tw/plugins/meta.git），安
 
 對 git diff 進行六組壞味道審查，每組一個 sub agent 平行執行；回報 `檔案:行號`、嚴重度、建議重構手法，修正與否由呼叫端決定。第 2 組同時擋「文件編號夾帶」：註解只寫「為什麼這樣寫」，議題編號、wiki 頁編號、工作包編號、commit hash、`@` 提及、外部文件連結一律不進註解，清單看 `references/comment-scope.md`。diff 是空的就直接回報「無發現」，不開任何 sub agent；六組全部回覆才進入彙整，沒東西可報的那組也要回「無發現」。安全性與 bug 審查交給 CLI 內建 review，不重複。
 
+### `api-doc`
+
+稽核 API 專案的 Swagger 文件：每個可能回傳的 HTTP 狀態碼都要宣告回覆類型，每個輸入與輸出都要有說明與真實資料範例，並沿著巢狀資料模型逐層遞迴。控制器改完或實作完成時執行，例如由 `jsc-sdlc:implement` 呼叫，與 `jsc-review:code-review` 並列為兩關收尾稽核。先跑 `tools/swagger-detect.sh` 偵測，套件與掛接設定要雙重命中才算支援；只裝套件沒掛接就回報未啟用並停手，不開任何 sub agent。原始碼的註解契約歸 `jsc-review:code-review` 第 5 組，這支只管 Swagger 文件屬性與範例，兩支不重複回報。回報 `檔案:行號`、嚴重度與建議修法，本技能不改程式碼。
+
 <!-- JSC-SKILLS:END -->
 
 ## 參考
@@ -37,6 +41,12 @@ Marketplace 統一為 `jsc`（https://gitea.jsc.idv.tw/plugins/meta.git），安
 | `references/smells.md` | 六組壞味道完整清單：定義、偵測訊號、建議重構手法、嚴重度分級；範例資料必須去識別化 |
 | `references/comment-scope.md` | 程式碼註解內容界線：禁止寫進註解的文件編號清單、允許項目與白名單、命中時的改法 |
 
+## 工具
+
+| 檔案 | 用途 |
+| --- | --- |
+| `tools/swagger-detect.sh` | 判斷專案有沒有真的啟用 Swagger。套件與設定雙重確認，缺一不算支援。輸出 `support=`、`stack=`、`package=`、`config=`；結束碼 0 支援、1 不支援、2 參數或路徑錯誤 |
+
 ## 相關 domain
 
 - [`jsc-sdlc`](https://gitea.jsc.idv.tw/plugins/sdlc)：實作階段完成後呼叫本審查
diff --git a/skills/code-review/SKILL.md b/skills/code-review/SKILL.md
index b8a472f..fdb9cff 100644
--- a/skills/code-review/SKILL.md
+++ b/skills/code-review/SKILL.md
@@ -16,6 +16,7 @@ Review changed code against `references/smells.md` (from the book *Refactoring*)
 
 - This skill covers the *Refactoring* smells, the comment contract (group 5), and shallow modules (group 6).
 - Security, logic bugs, and test coverage belong to the CLI's built-in review (e.g. claude's `/security-review`); do not duplicate them.
+- Swagger document auditing belongs to `jsc-review:api-doc`: response type declarations per HTTP status code, Swagger parameter descriptions, and Swagger examples down the nested data models. Group 5 here covers the source comment contract only; the two never report the same gap twice.
 
 ## Steps
 
@@ -28,7 +29,7 @@ Review changed code against `references/smells.md` (from the book *Refactoring*)
    | 2 Obscurity | smells.md group 2, including 2.5 document reference leak — comments carrying issue ids, wiki page ids, work package ids, commit hashes, @ mentions, or external document links; the full banned and allowed lists live in `references/comment-scope.md` |
    | 3 Couplers | smells.md group 3 |
    | 4 Dispensables & Others | smells.md group 4 |
-   | 5 Comment contract | smells.md group 5 |
+   | 5 Comment contract | smells.md group 5, 5.1 to 5.8 — including 5.6 navigation links to the functions a method calls, 5.7 XML comment tag layout (opening and closing tag each on its own line), and 5.8 code-element markup by language convention (`<paramref>`, `<see cref>`, `<c>` in XML; backticks in JSDoc and docstrings) |
    | 6 Shallow Module | smells.md group 6 |
 
    Instructions for each sub agent: read only, change nothing; check every changed line and its enclosing function or class against the group's definitions and detection signals in smells.md; report each finding as `file:line`, smell name, severity (高、中、低 per the smells.md scale), one sentence of evidence, and the suggested refactoring. Findings are reported in Traditional Chinese.