kanban-verify-completed-task

name	kanban-verify-completed-task
description	針對由其他 AI 完結的任務，進行至少三次以上的重複檢查。嚴格驗證所有內容是否符合原始需求、測試檔與文件是否已完整更新，並確保所有測試檔已通過執行測試。適用於任務交接或交付前的品質把關。
version	2.2.0
last_updated	"2026-05-28T00:00:00.000Z"
effective_date	"2026-05-28T00:00:00.000Z"

Kanban Verify Completed Task

🔴🔴🔴 工作主從鐵律（最高優先級，凌駕一切其他規則）

本 Skill 的工作有「主」與「從」之分，永遠不可顛倒：

🥇 主要工作（90% 比重，是真正交付的內容）

1. 實際撰寫專案程式碼：依 spec 與 plan 的需求，在專案實際的 src/、lib/、app/ 等目錄下新增/修改/刪除程式碼
2. 實際撰寫測試程式碼：在專案實際的 tests/、__tests__/、spec/ 等目錄下新增/修改測試檔
3. 實際執行測試指令：跑 npm test、pytest、yarn jest 等專案實際測試指令，確認 all green
4. 實際更新專案文件：README、docs/、API 文件等隨功能變動同步更新

🥈 次要工作（10% 比重，只是輔助記錄）

5. kanban 任務文件的內容更新：填欄位、勾 checkbox、寫測試結果摘要
6. kanban 資料夾與檔案搬移：跨階段 mv、建子資料夾、清理殘留

❌ 絕對禁止的錯誤理解

• ❌ 把「處理任務」理解成「只搬 markdown 檔案 + 改 markdown 內容 + 寫 summary」
• ❌ 認為「資料夾結構正確 + 狀態欄位正確 + summary 寫好 = 任務完成」
• ❌ 在沒有實際撰寫專案程式碼、測試程式碼、執行測試的情況下，就把 kanban 文件推到 7-Done/ 或 8-Archived/
• ❌ 把「執行 mv 與更新 markdown」當作「主要交付物」

✅ 正確理解

• ✅ kanban 文件的階段轉換僅僅是「實作進度的記錄」，不是「工作本身」
• ✅ 每一個 kanban 任務文件背後，都必須對應到實際的專案程式碼變動
• ✅ 沒有實際的 git diff（程式碼變動）、沒有實際的測試輸出，就禁止把任務推進到 7-Done/ 或 8-Archived/
• ✅ 寧可把 kanban 任務留在 3-Progressing/ 或 4-Testing/ 等待補實作，也不可在沒實作的狀況下把它推進到 done/archived

🚨 違規警報

若使用者在歸檔後檢查發現「kanban 文件已歸檔但專案程式碼根本沒動」，視為最嚴重的違規，等同欺騙使用者。本 Skill 為防止此類違規，在每個階段都加入「實作證據檢查」（見下方各階段強制規則與「🔴 歸檔前強制輸出檢查清單」Step C-2）。

路徑基準

本文件中提到的 templates/、scripts/、promps/、skills/，皆以目前語系內容根目錄為相對基準（例如 zh-TW/），不綁定 repo 根目錄固定路徑。

目的

本 skill 的主要目的是作為「品質防線 (Quality Gate)」。當一個任務已由其他 AI（或開發者）標示完成時，透過本 skill 進行至少三次深度、交叉比對的重複檢查，確保：

1. 實作內容完全符合原始需求與規格。
2. 相關文件 (Spec, Plan, README 等) 已正確同步更新。
3. 測試檔已針對修改或新增的功能對應更新或建立。
4. 所有牽涉到的測試皆已實際執行且顯示通過 (All green)。
5. 測試通過只能代表既有測試案例全綠，不得視為需求已完整完成的充分證明。
6. 必須逐條比對需求文件、Spec、Plan、驗收條件、使用者描述、實際程式碼、測試內容與執行結果，找出所有遺漏、行為不一致、邊界情境不足、文件不同步與可維護性風險。
7. 所有查證出的缺失、建議、需要補強的地方，以及後續實際修復或修改的內容，都必須完整詳細記錄到任務文件與歸檔 summary 中。
8. 執行 verify 時，除了檢查是否符合原始需求，也必須主動針對內容修改提出任何可讓需求、文件、測試或程式碼更完整的建議，並告知使用者。

🔴 全面需求符合度驗證鐵律（測試通過不等於任務完成）

本 skill 的真正驗證目標不是「測試有沒有通過」，而是「實際程式碼是否完整、正確、可維護地滿足需求文件」。

測試執行結果是必要證據，但只能作為其中一項證據。即使所有測試全綠，仍必須重新從需求文件出發，逐條追蹤到實際程式碼、測試案例與文件更新，確認沒有任何需求遺漏或需要補強之處。

強制需求追蹤矩陣

每次 verify 都必須建立並維護「需求追蹤矩陣」，至少包含下列欄位，並寫入相關任務文件或 archived summary：

需求來源	需求描述	對應程式碼檔案	對應測試檔案	實際驗證方式	驗證結果	缺失 / 建議 / 補強事項	修復或修改紀錄
Spec / Plan / README / 使用者描述	逐條列出，不得合併帶過	實際專案路徑	實際測試路徑	程式碼閱讀 / 測試 / 手動驗證 / 文件比對	✅ / ❌ / ⚠️	具體描述	實際修改內容與檔案

強制缺失與補強紀錄

只要發現任何缺失、風險、建議或需要補強的地方，就必須記錄到任務文件中；完成修復後也必須補上「實際修復或修改內容」。紀錄不得只寫摘要，必須具體到檔案、函式、行為與驗證方式。

強制內容修改建議審查

AI 執行本 skill 時，不得只做「是否通過」的二元判斷。每一輪 verify 都必須主動審查內容是否還有可以補充更完整、描述更清楚、測試更完善、實作更健壯或文件更一致的地方。

審查範圍至少包含：

1. 需求內容完整性：需求描述、驗收條件、邊界情境、錯誤流程、權限與安全性要求是否需要補充。
2. 程式碼修改完整性：實作是否有可讀性、可維護性、命名、錯誤處理、重複邏輯、資料驗證或相依性管理上的改善建議。
3. 測試內容完整性：是否需要新增正向流程、錯誤流程、邊界條件、權限情境、資料格式錯誤或整合測試。
4. 文件內容完整性：README、API 文件、Spec、Plan、任務文件與實際行為是否一致，是否需要補充使用方式、限制、注意事項或範例。
5. 交付內容完整性：是否有遺漏設定檔、環境變數說明、遷移步驟、部署注意事項、相容性說明或後續追蹤事項。

每一項建議都必須分類並告知使用者：

類別	說明	是否阻擋 verify 通過
必須修復	不符合需求、會造成錯誤、測試不足以證明需求、文件與行為不一致	是
強烈建議補強	不一定造成錯誤，但會影響可維護性、可讀性、使用者理解或未來擴充	依情境判斷，需告知使用者
可選改善	屬於品質提升或後續優化，不阻擋本次 verify，但必須記錄	否

若有任何建議或可補充更完整之處，必須在對話中明確列出，並寫入任務文件的「Verify 查核紀錄」。若使用者同意處理，完成後必須補上「實際修復或修改內容」與「修復後再驗證結果」。

每份被 verify 的任務文件必須包含或補上以下區塊：

## Verify 查核紀錄

### 需求追蹤矩陣

| 需求來源 | 需求描述 | 對應程式碼檔案 | 對應測試檔案 | 實際驗證方式 | 驗證結果 | 缺失 / 建議 / 補強事項 | 修復或修改紀錄 |
|----------|----------|----------------|--------------|--------------|----------|------------------------|----------------|

### 查證出的缺失

- [ ] ...

### 補強建議

- ...

### 內容修改建議審查

| 類別 | 建議內容 | 影響範圍 | 建議處理方式 | 是否已告知使用者 | 後續狀態 |
|------|----------|----------|--------------|------------------|----------|

### 實際修復或修改內容

- ...

### 修復後再驗證結果

- 測試指令：
- 測試結果：
- 需求再比對結果：

若任務已進入 8-Archived/，上述內容也必須同步反映到 [spec-xxxxx]-summary.md 的對應章節或補充章節中。

快速使用範例

• 觸發：$kanban-verify-completed-task
• 回覆：提供要檢查的任務路徑（如：特定目錄、相關的文件路徑、或 PR 連結等）。

互動問答流程（可用數字回答）

1. 來源 Plans / Spec 文件或資料夾路徑

• 請貼上要驗證的來源路徑（可多行，輸入 done 結束）。
• 可以是 plan 文件、spec 資料夾、完整的 task 資料夾，或 8-Archived 下的歸檔目錄。
• 例如：my-project/8-Archived/2026-04-01-[spec-xxxxx]-feature/

2. 重複檢查次數

• 預設會進行 3 次獨立交叉檢查，是否要更改次數？
• 直接按 Enter 或回覆 3 使用預設值，或輸入其他數字（最少 3 次）。

🔴 首要鐵律（不可違反）

強制執行至少三次的獨立檢查迴圈，每次檢查必須著重不同面向（例如：第一次逐條核對需求與程式碼、第二次核對文件、註解與測試覆蓋範圍、第三次執行測試並回頭確認測試是否真的覆蓋需求）。 只要在任一次檢查中發現需求遺漏、程式碼行為不符、測試不足、文件不同步、風險建議或測試失敗，必須立即將問題條列出來，寫入任務文件的 Verify 查核紀錄，並詢問使用者是否開始解決這些問題。如果使用者同意，則開始處理，處理完成後，自動開始跑下一輪檢查，一直反覆到所有輪數都完成，且沒有任何問題。 所有 verify 輪數完成且確認無缺失後，無論來源目前位於 1-Specs、2-Plans、3-Progressing、4-Testing、5-Re-testing、7-Done 或 8-Archived，都必須再執行一次 Archived 收尾流程；不得只停在總結報告，也不得把是否歸檔當成可省略選項。

🔴 階段格式鐵律（每階段必須先讀規範檔，禁止憑印象產出）

進入任何階段前，必須先 Read 對應的 RULES 與 template 檔案，再依其規定的「資料夾命名」、「子資料夾結構」、「檔案命名」產出文件與目錄。禁止憑記憶或推測產出格式。

每個階段對應的「進入前必讀」清單：

階段	進入前必讀（依序）
1-Specs	templates/COMMON_CONVENTIONS.md、templates/1-Specs/SPECS_RULES.md、templates/1-Specs/.specs-idea-to-docs-template.md
2-Plans	templates/2-Plans/PLANS_RULES.md、templates/2-Plans/PHASE_PRIORITY_GUIDELINES.md、templates/2-Plans/.plan-overview-template.md、templates/2-Plans/.plan-template.md
3-Progressing	templates/3-Progressing/PROGRESSING_RULES.md、templates/3-Progressing/.progressing-task-template.md
4-Testing	templates/4-Testing/TESTINGS_RULES.md、templates/4-Testing/.testing-task-template.md
7-Done	templates/7-Done/DONE_RULES.md、templates/7-Done/.done-task-template.md
8-Archived	templates/8-Archived/ARCHIVED_RULES.md、templates/8-Archived/.archived-summary-template.md

強制執行順序（每階段都要做）：

1. 先 Read 該階段所有 RULES / template 檔（不得跳過或只讀標題）
2. 依 RULES 的「資料夾結構範例」與「檔案命名規範」實際建立目錄樹
3. 依 template 的欄位逐一填入內容（欄位不足填 placeholder，不得省略章節）
4. 執行 mv 搬移檔案（嚴禁 cp）
5. 完成後立即驗證結構是否與 RULES 範例一致，不一致必須修正後才進下一階段

若 SKILL.md 與 RULES 文件出現衝突，以 RULES 文件為準（RULES 是該階段的最終真相來源）。

🔴 階段轉換鐵律 — 檔案位置與「狀態」欄位必須雙向同步

每次跨階段必須同時完成兩件事，缺一不可： (1) 將檔案實際 mv 到目標階段資料夾 (2) 將檔案內的「狀態」欄位同步更新為目標階段對應值

檔案位置與狀態欄位必須永遠一致。任何時刻檢查都必須吻合，不一致一律視為違規。

階段資料夾 ⇔ 「狀態」欄位對應表（強制）

所在資料夾	檔案內「狀態」欄位必須是
2-Plans/	待辦 (To Do)
3-Progressing/	處理中 (Progressing)
4-Testing/	測試中 (Testing)
5-Re-testing/	重新測試 (Re-testing)
6-On-hold/	暫停 (On-hold)
7-Done/	已完成 (Done)
8-Archived/.../done-plans/	已完成 (Done) ← 歸檔不改變狀態值，但必須已是 Done

跨階段標準操作流程（強制原子性，三步缺一不可）

每次跨階段都要依序完成以下 3 步：

1. 先更新檔案內容

   • 將「狀態」欄位改為目標階段對應值
   • 依目標階段 RULES 補齊該階段必填欄位（例如進入 3-Progressing 要新增「開始處理時間」、「實際使用的 AI 工具」、「開發進度」等）
   • 完成上一階段 Stage Exit Checkpoint：勾選所有 checkbox 為 [✓]、補齊本階段結果描述

2. 再執行 mv 搬移

   • 嚴禁 cp
   • 同批次有 0-PLAN_OVERVIEW 也要一併搬移並更新統計

3. 最後驗證一致性

   • 立即 Read 已搬移的檔案，確認「狀態」欄位顯示的階段名稱 = 檔案目前所在資料夾名稱
   • 不一致必須立即修正後才可繼續下一個動作

歸檔前的強制狀態檢查（絕對不可跳過）

進入 8-Archived 之前，必須對所有準備歸檔的 plan 文件逐一檢查：

1. 檔案目前是否真的在 7-Done/ 資料夾下（不在的話必須先把該檔案完整跑完該階段流程，禁止跳階段直接歸檔）
2. 檔案內「狀態」欄位的值是否為「已完成 (Done)」
3. 若狀態欄位不是「已完成 (Done)」，禁止歸檔，必須回到對應階段補完流程後再歸檔

驗證指令（強制執行，且結果必須全部通過）：

# 檢查所有準備歸檔的文件，狀態欄位是否都是「已完成 (Done)」
for f in <project>/7-Done/YYYY-MM-DD-[spec-xxxxx]-feature-name/*.md; do
  status=$(grep -m1 "^\*\*狀態" "$f")
  if ! echo "$status" | grep -q "已完成 (Done)"; then
    echo "❌ 違規檔案：$f"
    echo "   目前狀態：$status"
  fi
done

任一檔案違規時，立即停止歸檔流程、修正狀態欄位、重跑驗證指令直到全部通過，才可繼續歸檔。

🔴 歸檔前強制輸出檢查清單（最高優先級，必須在對話中完整輸出，缺一視為違規）

背景： 過往 AI 經常聲稱「已參考 ARCHIVED_RULES.md」但實際結構錯誤（例如檔案平鋪、summary 命名錯誤、來源未清理）。為徹底杜絕此問題，本 Skill 規定：進入 8-Archived 前，必須在對話中逐項完整輸出以下 6 步檢查內容，每一步都要有具體可驗證的輸出，禁止省略、合併或只說「已完成」。

此清單是強制性的對話輸出義務，不是內部執行步驟。使用者必須能在對話中親眼看到每一步的輸出。

Step A：引用宣告（必須照下方格式輸出）

在對話中輸出以下三行（替換實際路徑與行號）：

[歸檔前置作業]
✅ 已 Read templates/8-Archived/ARCHIVED_RULES.md（共 N 行）
✅ 已 Read templates/8-Archived/.archived-summary-template.md（共 N 行）
✅ 將依 ARCHIVED_RULES.md 第「📁 標準歸檔結構」章節範例建立目錄

Step B：來源檔案清單（必須輸出實際 ls 結果）

執行並輸出以下指令的實際結果：

ls -la <project>/1-Specs/YYYY-MM-DD-[spec-xxxxx]-feature-name/
ls -la <project>/7-Done/YYYY-MM-DD-[spec-xxxxx]-feature-name/

Step C：狀態欄位驗證（必須輸出實際指令結果）

執行並輸出「歸檔前的強制狀態檢查」驗證指令的實際結果。若有違規檔案必須先修正再回到 Step A 重來，禁止跳過此步驟。

Step C-2：實作證據檢查（最高優先級，禁止用空話帶過）

此步驟用於防止「kanban 文件已歸檔但專案程式碼根本沒動」的違規。必須在對話中逐項輸出實際證據，缺一視為違規。

C-2.1：列出本次實作涉及的所有專案程式碼檔案

執行並輸出（取代 <project-root> 為實際專案根目錄、<since-time> 為任務開始時間）：

# 列出本次任務新增/修改的程式碼檔案（非 kanban 檔）
git -C <project-root> status --short | grep -v "kanban/"
git -C <project-root> diff --name-only HEAD~N HEAD | grep -v "kanban/"

或若無 git，列出所有實際變動的程式碼檔案路徑（一行一個）。

自我檢查（必須在輸出後立即回答）：

• ❓ 上述清單是否包含至少一個 src/、lib/、app/、或專案實際程式碼目錄下的檔案？
• ❓ 若清單只有 kanban 檔案（*.md 在 kanban 目錄下），代表根本沒做實作工作，必須立即停止歸檔，回到 3-Progressing/ 補做實作。

C-2.2：列出本次撰寫的測試程式碼檔案

執行並輸出：

git -C <project-root> status --short | grep -E "test|spec|__tests__" | grep -v "kanban/"
git -C <project-root> diff --name-only HEAD~N HEAD | grep -E "test|spec|__tests__" | grep -v "kanban/"

自我檢查：

• ❓ 是否包含至少一個測試檔案的新增或修改？
• ❓ 若沒有任何測試檔變動，必須立即停止歸檔，回到 4-Testing/ 補做測試。

C-2.3：貼出最後一次測試執行的完整輸出

必須在對話中貼出本次任務最後一次執行測試的完整終端輸出，包含：

• 實際執行的測試指令（例如 npm test、pytest -v）
• 測試框架輸出的測試案例清單與結果
• 最終統計（passed / failed / total）

自我檢查：

• ❓ 輸出中是否顯示「all tests passed」或等價的全綠結果？
• ❓ 若無實際測試輸出，或測試有失敗，禁止歸檔，必須回到 4-Testing/ 或 5-Re-testing/ 補完。
• ❓ 若任務文件「測試結果」區塊是空的或只寫摘要，視為違規。

C-2.4：交叉比對 kanban 任務文件與實作

對於每一份準備歸檔的 plan 任務文件：

• ❓ 文件中「相關程式碼檔案」欄位列出的路徑，是否與 C-2.1 的清單對得上？
• ❓ 文件中「測試程式碼檔案」欄位列出的路徑，是否與 C-2.2 的清單對得上？
• ❓ 文件中「測試結果」區塊的指令與輸出，是否與 C-2.3 的實際輸出一致？

任一項對不上，代表 kanban 文件描述與實際實作脫節，禁止歸檔，必須先補對應內容。

Step D：宣告目標結構（必須輸出完整目錄樹）

在對話中輸出本次歸檔將建立的完整目標結構，並逐檔說明搬移對應關係。範例輸出格式：

[歸檔目標結構宣告]
8-Archived/2026-05-16-[spec-Qt9p1]-quota-reset-on-tier-change/
├── 1-Specs/
│   ├── [spec-Qt9p1]-IDEA_DESCRIPTION.md         ← 來自 1-Specs/.../[spec-Qt9p1]-IDEA_DESCRIPTION.md
│   └── [spec-Qt9p1]-CLEANUP_AND_INTEGRATION.md  ← 來自 1-Specs/.../[spec-Qt9p1]-CLEANUP_AND_INTEGRATION.md
├── done-plans/
│   ├── 0-PLAN_OVERVIEW.md                       ← 來自 7-Done/.../0-PLAN_OVERVIEW.md
│   ├── 2026-05-16-[spec-Qt9p1]-1-2-high-[plan-Lm3r7]-...md  ← 來自 7-Done/...
│   └── 2026-05-16-[spec-Qt9p1]-2-2-high-[plan-Pw8k2]-...md  ← 來自 7-Done/...
└── [spec-Qt9p1]-summary.md                       ← 新建（依 .archived-summary-template.md）

Step D 自我審查（必須在輸出後立即檢查）：

• ❓ summary 檔名是否為 [spec-xxxxx]-summary.md？（不是 ARCHIVED_SUMMARY.md 等變體）
• ❓ 是否有 1-Specs/ 與 done-plans/ 兩個子資料夾？
• ❓ 是否所有檔案都歸位到子資料夾，沒有平鋪在根目錄？
• ❓ 根資料夾是否使用 [spec-xxxxx] 而非 [plan-xxxxx]？

任一答案為「否」，必須立即修正宣告後重來。

Step E：執行 mkdir + mv（必須逐個指令輸出）

依 Step D 宣告依序執行 mkdir -p 與 mv 指令。每個指令都必須在對話中可見，不得用一個 && 串起來掩蓋細節。

Step F：執行收斂驗證（必須輸出實際指令結果）

執行並輸出以下兩組指令的實際結果：

# 驗證 1：歸檔結構完整
ls -R <project>/8-Archived/YYYY-MM-DD-[spec-xxxxx]-feature-name/

# 驗證 2：來源無殘留
find <project>/{1-Specs,2-Plans,3-Progressing,4-Testing,5-Re-testing,6-On-hold,7-Done} \
  -type f -name "*[spec-xxxxx]*" 2>/dev/null

驗證 1 結果必須符合 Step D 宣告。 驗證 2 結果必須為空。 任一不符必須立即修正，並重跑驗證指令直到通過。

Step G：歸檔後最終回頭驗證（強制，禁止省略，禁止與 Step F 合併）

此步驟是「自我審計」，目的是抓出 Step A~F 過程中可能漏看或自欺的問題。 即使 Step F 通過，仍必須執行 Step G 完整的雙重對照。發現任何不一致必須立即修正並重跑此步，直到全部通過才可宣告歸檔完成。

G-1：重新 Read 模板，對照歸檔結構（結構對照）

1. 重新 Read templates/8-Archived/ARCHIVED_RULES.md（即使 Step A 已讀過，此處必須再讀一次）
2. 重新 Read templates/8-Archived/.archived-summary-template.md
3. 執行並輸出 ls -R <project>/8-Archived/YYYY-MM-DD-[spec-xxxxx]-feature-name/ 的實際結果
4. 逐項對照表格（必須在對話中完整輸出）：

規範項目	規範來源	實際結果	是否符合
歸檔根資料夾命名為 YYYY-MM-DD-[spec-xxxxx]-feature-name/	ARCHIVED_RULES.md「✅ 命名與結構」	（填入實際資料夾名）	✅ / ❌
含 1-Specs/ 子資料夾	ARCHIVED_RULES.md「📁 標準歸檔結構」	（是 / 否）	✅ / ❌
含 done-plans/ 子資料夾（不是 done-tasks/）	同上	（是 / 否，實際名稱）	✅ / ❌
1-Specs/ 內檔名為 [spec-xxxxx]-XXX.md	SPECS_RULES.md	（列出實際檔名）	✅ / ❌
done-plans/ 內檔名格式為 YYYY-MM-DD-[spec-xxxxx]-N-優先級-[plan-yyyyy]-類別-描述.md	COMMON_CONVENTIONS.md	（列出實際檔名）	✅ / ❌
summary 檔名為 [spec-xxxxx]-summary.md（不是 ARCHIVED_SUMMARY.md 等變體）	ARCHIVED_RULES.md「Summary 檔名」	（填入實際 summary 檔名）	✅ / ❌
summary 內容章節完整（依 .archived-summary-template.md 全部章節都在）	.archived-summary-template.md	（列出 summary 章節清單）	✅ / ❌
沒有任何檔案平鋪在歸檔根資料夾（除了 summary）	ARCHIVED_RULES.md「禁止事項」	（列出根目錄檔案）	✅ / ❌
來源 7 個階段資料夾無殘留	ARCHIVED_RULES.md「步驟 7 / 步驟 8」	（貼 find 指令結果）	✅ / ❌

任一項為 ❌，必須立即修正後重跑 Step G。

G-2：重新 Read 每個歸檔檔案，檢查內容與狀態（內容狀態檢查）

對 8-Archived/YYYY-MM-DD-[spec-xxxxx]-feature-name/ 下的每一個 .md 檔案執行以下檢查（不可省略任何一個檔案，不可只抽樣）：

G-2.1：plan 任務文件（done-plans/ 下的每一份）

對每一份 plan 任務文件 Read 後，輸出檢查表：

檔案	「狀態」欄位	開發進度全 [✓]	測試進度全 [✓]	「相關程式碼檔案」非空且非 kanban 路徑	「測試程式碼檔案」非空	「測試結果」區塊含完整指令與輸出	完成標記是 [✓] 而非 [x]
xxx-plan-Az4a2-...md	必須是「已完成 (Done)」	✅ / ❌	✅ / ❌	✅ / ❌	✅ / ❌	✅ / ❌	✅ / ❌
xxx-plan-By3n1-...md	...	...	...	...	...	...	...

任一欄為 ❌，必須立即補正該檔案後重跑 Step G。

G-2.2：0-PLAN_OVERVIEW（若有）

Read overview 後檢查：

• ❓ 「最後更新時間」是否為最新（歸檔當下時間，而非舊時間）？
• ❓ 任務統計是否與實際 done-plans 數量一致？
• ❓ 所有任務狀態是否都標記為「已完成」？
• ❓ 整體進度是否為 100%？

任一項否，補正後重跑 Step G。

G-2.3：1-Specs 文件（IDEA_DESCRIPTION、CLEANUP_AND_INTEGRATION 等）

Read 後檢查：

• ❓ 內容是否反映實際完成狀況（而非任務開始時的初始草稿）？
• ❓ 「驗收條件」、「成功指標」等欄位是否更新為實際達成的結果？
• ❓ 若 spec 文件中提到的需求在實作過程有調整，是否已回寫到 spec？

任一項否，補正後重跑 Step G。

G-2.4：summary

Read summary 後檢查：

• ❓ 所有章節是否完整（對照 .archived-summary-template.md，缺章節必須補）？
• ❓ 「歸檔時間」是否為實際當下時間？
• ❓ 「總任務數」、「任務分類統計」、「平均測試覆蓋率」、「平均測試成功率」是否與 done-plans 實際數據一致？
• ❓ 「主要成果」、「技術棧」、「學到的經驗」是否有具體內容（非 placeholder）？
• ❓ 「相關連結」（git commit / PR）若已知必須填入？

任一項否，補正後重跑 Step G。

G-3：最終總結報告（必須在對話中輸出）

完成 G-1 + G-2 全部檢查並全綠後，必須輸出以下總結（照填）：

[歸檔最終驗證報告]

📐 結構對照（G-1）：
  - ARCHIVED_RULES.md 規範項：N 項全部符合 ✅
  - 無平鋪、無殘留、無命名錯誤 ✅

📄 內容狀態檢查（G-2）：
  - plan 任務文件數：X 份
    - 全部「狀態」= 已完成 (Done) ✅
    - 全部「相關程式碼檔案」非空且指向實際專案路徑 ✅
    - 全部「測試結果」含實際測試輸出 ✅
  - 0-PLAN_OVERVIEW：統計數據與實際一致 ✅
  - 1-Specs 文件：內容已回寫實際完成狀況 ✅
  - summary：所有章節完整、數據一致、無 placeholder ✅

🎯 歸檔狀態：完成且通過所有驗證

任一項為 ❌ 或不確定時，禁止輸出此總結，必須先修正後重跑 Step G。

---

🚨 重要原則：

• 此 7 步（A~G）是對話可視義務，不是內部執行步驟。AI 不得用「我已完成歸檔流程」一句話帶過。
• 任一步輸出不完整，使用者有權要求重做整個歸檔流程。
• 此清單優先於 SKILL 內任何「簡化」或「優化」指令。即使使用者說「快速歸檔」、「不用詳細輸出」，也必須完整輸出此 7 步。
• Step G 是最後一道防線，禁止與 Step F 合併、禁止跳過、禁止用 Step F 的結果取代。 Step F 是「執行驗證」，Step G 是「重新對照模板進行自我審計」，兩者目的不同，必須分開執行。

必做步驟

1. 資訊收集與準備

• 確認要檢查的來源路徑。
• 讀取其對應的原始需求、Spec、Plan、README、API 文件、使用者補充說明與驗收條件。
• 將所有需求拆成可逐條驗證的需求清單，不得只用整體摘要帶過。
• 收集所有在本次任務中被修改或建立的原始碼、測試檔、設定檔、遷移檔、文件與任務文件清單。
• 建立「需求追蹤矩陣」，把每一條需求對應到實際程式碼檔案、測試檔案與驗證方式。
• 若找不到某條需求的對應程式碼或測試，必須立即標記為缺失或需要補強，不得因為既有測試通過就忽略。

2. 第一回合：需求與規格比對檢查 (Round 1: Requirement Alignment)

• 從需求文件出發，逐條追蹤到實際程式碼邏輯、資料流、錯誤處理、權限檢查、邊界條件與使用者可見行為。
• 將修改後的程式碼邏輯與 Spec/Plan 上的驗收標準 (Acceptance Criteria) 逐一比對。
• 確認所有列出的需求都已被滿足，沒有遺漏功能，也沒有多做不在範圍內的功能。
• 檢查是否存在「測試有寫到，但需求沒有要求」或「需求有要求，但測試與程式碼沒有處理」的落差。
• 將每一項比對結果寫入「需求追蹤矩陣」，並清楚標示 ✅ 通過、❌ 缺失、⚠️ 需要補強。
• 若發現缺失或需要補強，必須具體記錄：需求來源、缺失描述、影響範圍、建議修法、預計修改檔案。
• 即使需求已符合，也必須檢查是否有讓內容更完整、規格更清楚、錯誤情境更明確或實作更健壯的建議，並告知使用者。

3. 第二回合：文件與測試範圍檢查 (Round 2: Doc & Test Coverage)

• 檢查關聯任務文件狀態及勾選項目是否已詳實填寫。
• 檢查測試檔 (.test.ts, .spec.ts 等) 內容：確認其涵蓋了正向路徑 (Happy path)、預期的錯誤情境 (Edge cases)、權限或安全性情境、資料為空或格式錯誤情境，以及需求中特別指定的例外流程。
• 檢查測試名稱、測試資料與 assertion 是否真的驗證需求行為，而不是只驗證函式有被呼叫或 snapshot 沒變。
• 檢查測試是否有過度 mock 導致未驗證真實行為；若有，必須列為補強建議。
• 確認修改到的功能如有架構異動，對應的 README 或教學文件是否有同步更新。
• 確認任務文件已記錄所有查證出的缺失、建議、需要補強之處，以及後續實際修復或修改內容。
• 若 README、API 文件、Spec、Plan 與實際程式碼行為不一致，必須列為缺失並修正或明確記錄為待使用者決策。
• 主動檢查所有文件內容是否還有可補充更完整的地方，例如限制條件、使用範例、環境變數、部署注意事項、測試方式、錯誤排查方式與後續維護建議。

4. 第三回合：執行測試與結果驗證 (Round 3: Test Execution & Validation)

• 實際執行相關的測試指令（需涵蓋修改過的元件、API 或是整個 test suite）。
• 若專案層級還有 lint 或 type-check 指令，一併執行確保語法正確。
• 確認終端機輸出結果呈現為完全通過 (All tests passed)。
• 測試通過後，必須回頭確認測試案例是否覆蓋第一回合建立的每一條需求；若沒有覆蓋，仍視為 verify 未完成。
• 若沒有發生任何錯誤，在相關任務文件內補上測試通過的截錄記錄、需求再比對結果、未發現缺失的明確理由。
• 若修復過任何缺失，必須再次執行受影響測試，並把「修復前缺失 → 修改內容 → 修復後驗證結果」完整記錄到任務文件。
• 測試全綠後仍必須輸出「內容修改建議審查」結果；若沒有任何建議，也必須明確寫出「未發現需補強建議」及判斷依據，不得省略此步驟。

5. Archived 收尾流程（Verify 完成後強制執行）

• 在所有 verify 輪數通過後，必須先判定來源路徑目前所處的階段，並依下列規則立即接續對應的 archived 流程，不可跳過：
  • 來源在 1-Specs/：執行 kanban-exist-specs-push-to-archived
  • 來源在 2-Plans/ 或 3-Progressing/：執行 kanban-exist-plans-push-to-archived
  • 來源在 4-Testing/ 或 5-Re-testing/：執行 kanban-exist-testing-push-to-archived
  • 來源在 7-Done/：執行 kanban-archive-only
  • 來源已在 8-Archived/：仍必須再次比對 templates/8-Archived/ARCHIVED_RULES.md、summary 模板、來源清理結果與 archived 目錄結構；若任一項不符，立即補齊到完全符合 archived 規範為止
• 若同一批來源橫跨多個階段，必須先依相依性整理批次，再從最前面的未完成階段開始推進到 8-Archived，不可只處理其中一部分。
• Archived 收尾流程完成後，必須再次確認：
  • 最終權威文件只存在於 8-Archived/
  • summary 已存在且內容符合模板
  • 中間階段無殘留同批次文件或空資料夾
  • verify 過程補上的測試結果、文件修正、checkbox 狀態都已反映到 archived 最終文件

6. 總結報告與後續處理 (Final Report & Next Steps)

• 在所有輪數檢查全數通過，且沒有任何問題後，產出一份總結報告。
• 條列這幾次檢查中所確認的重點（例：已逐條檢查 8 項需求、已確認 3 個測試檔涵蓋範圍、已執行測試共 15 個 test cases 皆通過）。
• 報告中必須列出需求追蹤矩陣摘要、查證出的缺失清單、補強建議清單、實際修復或修改內容清單，以及修復後再驗證結果。
• 報告中必須列出「內容修改建議審查」摘要，包含必須修復、強烈建議補強、可選改善三類項目；若沒有建議，必須列出明確判斷依據。
• 報告中必須明確列出本次 verify 完成後，實際接續執行的 archived 流程名稱、最終 archived 目錄路徑、summary 文件路徑，以及已清除的中間階段殘留路徑。
• 只有在 archived 收尾流程也完成後，整個 verify 才算真正結束。
• verify + archived 全部完成後，接著詢問使用者：「是否開始跑 git-add-and-gen-commit-message 的 skill？」
• 若使用者同意，就開始執行該 git skill。

安全停止條件與問題處理流程

• 每一輪的檢查中，如果發現有問題、缺失、bug、需求未覆蓋、測試不足、文件不同步、可維護性風險、內容可補充更完整之處或任何修改建議，立即列出問題與建議清單，寫入任務文件的 Verify 查核紀錄，並詢問使用者是否開始解決這些問題或採納建議。
• 若使用者同意，則自動開始修復程式碼、測試或文件。修復完成後，必須把實際修復或修改內容寫入任務文件，再自動開始跑下一輪檢查（重新跑流程確保無遺漏），反覆此流程直到所有輪數完成且零缺失。
• 若使用者暫時不處理缺失或建議，仍必須把缺失、建議、影響範圍、建議處理方式與未處理原因記錄到任務文件。若屬「必須修復」類別，不得宣稱 verify 通過。
• 若 verify 已通過，但 Archived 收尾流程中發現結構、summary、搬移位置或來源清理仍不符合規範，視為 verify 尚未真正完成；必須先補齊 archived 狀態，再回到最終報告。
• 只有在使用者明確選擇不處理，或是發現即使經過反覆修復仍無法解決的嚴重錯誤時，才真正停止並交由使用者了解狀況。

禁止事項

• 絕對不得只做一次檢查就宣稱「檢查了三次完成」。必須在工作過程 (日誌或思考流程) 中實質展現三次獨立的檢查。
• 絕對不得在未實際執行測試 (yarn test 或相似指令) 的情況下，假定或虛構測試結果通過。
• 絕對不得把測試通過視為需求已完整完成的充分證明。測試全綠後仍必須逐條比對需求文件、Spec、Plan、程式碼、測試與文件。
• 絕對不得只檢查測試檔是否通過，而未檢查實際程式碼是否完整符合需求、是否有遺漏需求、是否需要補強、是否有文件不同步。
• 絕對不得省略需求追蹤矩陣。每一條需求都必須有對應程式碼、測試或明確缺失紀錄。
• 絕對不得發現缺失或建議後只在對話中說明而不寫入任務文件或 archived summary。
• 絕對不得在 verify 時只回報錯誤，不主動提出內容可以補充更完整、修改更清楚、測試更完善或文件更一致的建議。
• 絕對不得因為需求已通過就省略「內容修改建議審查」。即使沒有建議，也必須記錄「未發現需補強建議」與判斷依據。
• 絕對不得把「可選改善」與「必須修復」混在一起。必須清楚分類，避免使用者誤以為所有建議都阻擋 verify，或誤以為阻擋項目只是可選改善。
• 絕對不得完成修復後只說「已修復」。必須記錄實際修改檔案、修改內容、修復原因、修復後測試指令與需求再比對結果。
• 絕對不得自行幫使用者掩蓋缺少的情境，必須將發現的缺漏回報給使用者。
• 絕對不得在 verify 完成後只提供總結而未再執行 archived 收尾流程。
• 絕對不得在來源仍位於 1-Specs、2-Plans、3-Progressing、4-Testing、5-Re-testing 或 7-Done 時，宣稱任務已完成 archived 狀態。
• 絕對不得在進入任一階段前，跳過該階段對應的 RULES / template 檔案閱讀（憑印象產出格式）。
• 絕對不得將 plan 文件、0-PLAN_OVERVIEW.md、spec 文件平鋪到 8-Archived/YYYY-MM-DD-[spec-xxxxx]-feature-name/ 根目錄；必須分別放入 1-Specs/ 與 done-plans/ 子資料夾。
• 絕對不得將 archived summary 命名為 ARCHIVED_SUMMARY.md、SUMMARY.md 或其他變體；必須使用 [spec-xxxxx]-summary.md 或 [no-spec]-summary.md。
• 絕對不得在歸檔完成後，留下 1-Specs/、2-Plans/、3-Progressing/、4-Testing/、5-Re-testing/、6-On-hold/、7-Done/ 中該批次 spec 的殘留資料夾或檔案。
• 絕對不得使用 [plan-xxxxx] 作為歸檔根資料夾識別（必須使用 [spec-xxxxx] 或 [no-spec]）。
• 絕對不得使用 done-tasks/ 舊名稱（必須使用 done-plans/）。
• 絕對不得只搬移檔案而不更新檔案內「狀態」欄位；也不得只更新「狀態」欄位而不搬檔案。兩者必須在同一次跨階段操作中同步完成。
• 絕對不得讓檔案內「狀態」欄位與檔案目前所在資料夾不一致（例如檔案在 4-Testing/ 卻寫「處理中 (Progressing)」、檔案在 8-Archived/ 卻寫「測試中 (Testing)」）。
• 絕對不得將「狀態」欄位不是「已完成 (Done)」的文件搬入 8-Archived/。歸檔前必須先跑「歸檔前的強制狀態檢查」驗證指令，確認全數通過。
• 絕對不得跳階段（例如直接從 3-Progressing/ 跳到 7-Done/，或從 4-Testing/ 跳到 8-Archived/），每個階段都必須依序經過。
• 絕對不得跳過或簡化「🔴 歸檔前強制輸出檢查清單」的 7 步輸出（A 到 G）。即使使用者要求「快速歸檔」、「不用詳細輸出」，也必須完整輸出 7 步，且每一步都要有具體可驗證的輸出（實際 ls / find / grep 指令結果），不得用「已完成」一句話帶過。
• 絕對不得跳過或簡化 Step G「歸檔後最終回頭驗證」。Step F 與 Step G 目的不同，禁止合併、禁止用 Step F 取代 Step G。Step G 必須包含：(1) 重新 Read ARCHIVED_RULES.md 並逐項對照表格、(2) Read 每一份歸檔檔案檢查內容與狀態、(3) 輸出最終驗證總結報告。
• 【最嚴重違規】絕對不得只搬 kanban markdown 檔案、只更新 kanban 文件內容、只寫 summary 就推進到 7-Done/ 或 8-Archived/，而沒有實際撰寫專案程式碼、測試程式碼與執行測試。kanban 文件管理是次要工作，實際的程式碼與測試實作才是主要交付物。
• 絕對不得讓 kanban 任務文件的「相關程式碼檔案」、「測試程式碼檔案」、「測試結果」欄位為空或只填 placeholder 就推進到下一階段。這些欄位必須對應到實際的專案程式碼變動，並能通過「🔴 歸檔前強制輸出檢查清單 Step C-2 實作證據檢查」。
• 絕對不得把「執行 mv + 改 markdown 內容」誤解為「完成任務」。任務的真正完成標準是：專案程式碼實作完畢 + 測試程式碼撰寫完畢 + 測試實際執行通過 + 專案文件更新完畢，kanban 文件只是這些工作的記錄載體。