Consistency Audit — 五步工作流詳解
本檔為
SKILL.md引用的詳細工作流指南。在每次 audit 開始前讀一次。
前置條件
進入 audit 前確認：
- 有實際 diff 可看 — git diff 或前後文，缺一不可
- 改動寫進文件了 — 不是腦海中的計畫
- 改動有語意影響 — 純 typo / 排版不算
不符合任一條 → 明說缺什麼、停下。
步驟 1 — 取得 diff
目標：拿到改動前後的對照，作為 audit 的唯一輸入。
優先序
-
git diff（最佳）
請執行： git diff HEAD -- spec/{feature}/{feature}.fp.md 或： git diff {base-branch}...HEAD -- {file} 把結果貼給我。有 commit context、可看修改範圍與 commit message。
-
前後文貼上
請使用者用以下格式：
檔案：{path} <old> ...改動前內容... </old> <new> ...改動後內容... </new>多個改動段就重複
<old>/<new>區塊。 -
新版 + 改動章節清單（精度差）
使用者貼完整新版檔，並明說「改了 §1.2 跟 §3 邊界條件」。 可用但精度打折 — 你看不到舊版實際語意。
對齊
我拿到的 diff：
- 檔案：spec/login/login.fp.md
- 變更段落：§2 UC A1 行為步驟、§4 邊界條件 B3 新增
- Diff 大小：約 30 行
我會以這份為 audit 唯一輸入。接下來進步驟 2，先對齊修改階段。
異常
- diff 無實質改動（純空白、排版）→ 「沒有語意改動，audit 可略過」並停下
- diff 跨多個階段檔（同時動了 FS 跟 OOA）→ 拆成多輪 audit，逐檔走
步驟 2 — 對齊修改階段
目標：判定改動文件所屬階段，決定接下來走哪張 audit 範圍表。
階段判定
| 檔案路徑 | 階段 | 走哪張表 |
|---|---|---|
requirement/{feature}/* | Stage 1 Requirement | 不是 mid-stage edit；走 A 路徑，不用 audit |
spec/{feature}/{feature}.fp.md | Stage 2 Functional Spec | §3a 修改 FS |
spec/{feature}/{feature}.ooa.md | Stage 3 OOA | §3b 修改 OOA |
spec/{feature}/{feature}.pseudo.md | Stage 4 Pseudo Code | §3c 修改 Pseudo Code |
*.java / *.kt / Code | Stage 5 Code | 紅線：不允許跳過文件直接動 Code；本 skill 拒絕做 code-only audit |
對齊
本次改動位於 Stage 2 Functional Spec。
接下來：
- 上游比對：往 Stage 1 Requirement 看
- 下游影響：往 OOA / Pseudo Code / Code 看
步驟 3a — 修改了 Functional Spec 的 audit 範圍
上游一致性（往 Requirement 看）
| 檢查項 | 問句 |
|---|---|
| Problem Statement 範圍 | 改動是否仍在 requirement/{feature}/index.md 的 Problem statement 範圍內？ |
| 需求收斂結論範圍 | 改動是否仍在 index.md 的「需求收斂結論」範圍內？是否與其「已定向」項衝突，或自行拍了結論裡列為「仍待 Stage 2 拍板」的點？ |
| Requirement 素材覆蓋 | 是否引入了 requirement 沒記錄的 user need？ |
| 既有素材矛盾 | 是否與 requirement raw/ 或 notes/ 中的既有筆記矛盾？ |
例外 —— 共用／跨 feature spec（如
domain-model.md，設計上無 requirement 上游，見product-module-development-workflow.md§可追溯性 → 共用／跨 feature spec）：整張上游表的 requirement 比對全部略過，不因「requirement 不存在」判 ❌。改以單一檢查取代 —— 「本次改動是否引入任何消費方 spec 都未涵蓋的概念？」有 → ⚠️（需確認補進某消費方或回 Stage 1）、無 → ✅。
下游影響（往 OOA / Pseudo Code / Code 看）
| 檢查項 | 問句 |
|---|---|
| Use Case 對應的物件 | 哪些 Use Case 被改 → spec/{feature}/{feature}.ooa.md 對應的 Object Model 元素？ |
| I/O 範例對應的 § | 哪些 I/O 範例被改 → spec/{feature}/{feature}.pseudo.md 對應的 §X.Y.Z 需重看？ |
| 邊界條件新增 | 是否新增了 §{SHORT}-FS-{n} 邊界 → 下游 pseudo-code 是否覆蓋此分支？ |
| Code 引用 | 被改的邊界是「對外」項目 → 直接 grep 其全域碼 §{SHORT}-FS-{n}（跨 vault + code repo）找所有引用 |
步驟 3b — 修改了 OOA 的 audit 範圍
上游一致性（往 Functional Spec 看）
| 檢查項 | 問句 |
|---|---|
| Model 服務的 Use Case | Model 是否仍能服務 spec/{feature}/{feature}.fp.md 的所有 Use Case？ |
| 引入未提的概念 | 是否引入了 functional spec 沒提到的概念？若有，是純技術抽象還是業務概念？ |
下游影響（往 Pseudo Code / Code 看）
| 檢查項 | 問句 |
|---|---|
| § 引用的類別 / 方法 | 哪些 pseudo-code §X.Y 的「對應實作」引用了被改動的 class / method？ |
| Domain Event 名稱 | 哪些 § 引用了被改名的領域事件？ |
| Code 引用 | 哪些 .java 直接實作了被改動的類別 / 介面？ |
步驟 3c — 修改了 Pseudo Code 的 audit 範圍
上游一致性（往 Functional Spec 看）
| 檢查項 | 問句 |
|---|---|
| 流程對應 Use Case | 流程是否仍對應 spec/{feature}/{feature}.fp.md 的 Use Cases？ |
| 分支完整 | 邊界條件 B1 ~ B{n} 是否每條都還有對應的 pseudo-code 分支？ |
| 新增分支 | 是否新增了 functional spec 沒列的邊界？若有，需回去補 FS 還是該分支屬於實作細節？ |
下游影響（往 Code 看）
| 檢查項 | 問句 |
|---|---|
| Javadoc § 引用 | 被改的對外 §-section → grep 其全域碼 §{SHORT}-PC-{N}（跨 vault + code repo）找所有 Javadoc 引用；純內部子節點則 grep 本地 §X.Y.Z |
| 編號穩定 | 是否違反 §編號 append-only 規則（廢棄段落沒留刪除線、或重編／重用號碼）？若違反 → 自動 ❌ |
| 測試覆蓋 | 哪些測試對應到被改的 §？需要重跑或重寫？ |
步驟 4 — 上游一致性比對
目標：對該階段的 audit 範圍逐項比對，產出狀態與說明。
操作
對每一項：
- 找出對應上游章節的當前內容（用 Read 工具）
- 跟 diff 後的內容比對
- 判定狀態 ✅ / ⚠️ / ❌
- 寫一句說明（含具體出處）
狀態判定準則
✅ 一致：
- 改動完全落在上游約束內，可直接通過
- 例：FS 把 UC A1 的步驟順序調整，但所有步驟仍對應 requirement 中已存在的需求
⚠️ 需討論：
- 改動不直接違反上游，但有 implication 需人裁定
- 例：FS 新增了 UC A4，requirement 沒明寫此 actor 行為，但也沒明確禁止 — 需 stakeholder 確認
- 不確定時一律 ⚠️，不要替使用者放行為 ✅
❌ 矛盾：
- 改動直接違反上游明文規定，或讓上游既有內容失效
- 例：FS 改了 UC A1 的預期結果，跟 requirement 的 Problem statement 矛盾
- 例：OOA 移除了某個類別，但 FS 中該類別對應的 Use Case 還在
- ❌ 必須有具體出處：「上游 §X 規定 Y，本次改動違反此規定」
對齊
完成上游比對後，先呈現給使用者，等回應再進步驟 5。
上游一致性檢查完成：
| 項目 | 狀態 | 說明 |
| Problem Statement 範圍 | ✅ | 改動在範圍內 |
| Requirement 素材覆蓋 | ⚠️ | UC A4 引入了 R5 未記錄的 actor 行為 |
| 既有素材矛盾 | ✅ | 無 |
⚠️ 項目我會列進「需討論清單」。要不要先處理 UC A4 這條？
或直接進下游影響評估？
步驟 5 — 下游影響評估
目標：對該階段的 audit 範圍逐項找出受影響的下游章節與檔案。
操作
對每一項：
- 找出對應下游檔案（用 Glob / Read）
- 找出引用了被改動內容的具體章節 / 行號 / Javadoc §
- 被改項是「對外」項目（有全域碼）時，直接 grep 全域碼
§{SHORT}-{TYPE}-{NUMBER}——全域唯一、跨 vault + code repo 一網打盡，本身即反向索引（見 workflow §可追溯性「全域編碼」）。
- 被改項是「對外」項目（有全域碼）時，直接 grep 全域碼
- 寫成「受影響章節 + 行動標籤」
行動標籤定義
| 標籤 | 意義 |
|---|---|
| 需更新 | 下游內容直接受影響，必須改動才能保持一致 |
| 需重看 | 不一定要改，但需人讀過確認影響範圍 |
| 測試重跑 | code 行為可能變，對應測試需重跑 |
| 引用失效 | Javadoc 或文件內的 § 引用已不存在，必須修引用 |
不開處方
你列受影響章節 + 行動標籤。怎麼修不由你寫，回到該階段的 AI/人 邊界。
❌ 不寫：
| spec/login/login.ooa.md | §3 User class | 把 username 改成 email |
✅ 寫：
| spec/login/login.ooa.md | §3 User class | 需更新（FS 把 input 從 username 改成 email） |
對齊
完成下游影響後，呈現給使用者：
下游影響評估完成，共 {N} 個受影響點：
| 下游文件 | 受影響章節 | 行動 |
| spec/login/login.ooa.md | §3 User class | 需更新 |
| spec/login/login.pseudo.md | §2.1 驗證流程 | 需重看 |
| LoginService.java | line 42-78 | 測試重跑 |
接下來我會組裝完整 Impact Report 寫到磁碟，OK 嗎？
步驟 6 — 組裝 Impact Report 並寫檔
目標：把所有發現組裝成標準 markdown，寫進 audit/。
操作
- 套
output-template.md組裝完整 Impact Report - 寫到
audit/{feature}-{YYYY-MM-DD}-{stage}.md- feature：跟改動文件同名
- 日期：今日
- stage：
fs/ooa/pseudo-code - 範例：
audit/login-2026-06-01-fs.md
- 文件底部留三條簽核欄
- 提示使用者：
- ❌ 項目若存在 — 必須處理才能簽核該階段文件
- ⚠️ 項目進討論清單
- 下游更新請開對應階段的 partner skill 執行
收尾話術
Impact Report 我整理好了：
- 上游：{N} ✅、{M} ⚠️、{K} ❌
- 下游：{X} 個受影響點
我會寫到 audit/{feature}-2026-06-01-fs.md，留三條簽核欄給你。
❌ 矛盾共 {K} 條，建議先處理才簽核 spec/{feature}/{feature}.fp.md（這是 Exit Gate 一致性要求）：
- ❌1：...
- ❌2：...
要直接寫檔嗎？
異常情境
diff 大到走不完
跨檔、跨多個 § 的大量改動 → 提議拆批：
這次 diff 影響 {N} 個下游檔。一次走完 audit 報告會太長，建議拆三批：
A. UC A1 ~ A3 的影響
B. 邊界條件 B1 ~ B5 的影響
C. 其他
要依此拆嗎？還是你優先想看哪一批？
改動跨多個階段（FS + OOA 同時改了）
不混在一輪做。逐檔分別走 audit。每份 Impact Report 對應一個階段的改動。
你這次同時改了 spec/login/login.fp.md 跟 spec/login/login.ooa.md。
我建議跑兩輪 audit：
1. FS 改動的 audit（上游看 requirement、下游看 OOA / pseudo / code）
2. OOA 改動的 audit（上游看 FS、下游看 pseudo / code）
兩輪的下游可能有重疊但會分開呈現。先跑哪一輪？
改動只動了 code 沒動文件
直接拒絕：
這份 diff 只動了 code、沒動文件。
依 workflow §核心紅線：「任何路徑都不允許跳過文件直接動 Code」。
建議先回去把對應的 pseudo-code §（或上游階段）同步，再來 audit。
例外：使用者明確說是 refactor 不變行為，那也應該先確認 Javadoc 中的 § 引用仍對得上，不需 audit 但需檢查 § 對應。
上游文件不存在
例如 audit FS 改動，但 requirement/{feature}/index.md 不存在 → 把這件事本身列為 ❌：
❌ 無法 audit 上游：requirement/{feature}/index.md 不存在。
本次 FS 改動沒有可比對的 requirement 來源，依工作流要求應補上才能簽核。
例外 —— 共用／跨 feature spec：若該 FS 本就是共用 spec（如 domain-model.md，設計上無 requirement 上游），不判 ❌。標記為「共用 spec、無 requirement 上游（符合設計）」，改走步驟 3a 的共用 spec 例外檢查。