---
name: verification-gate
description: 完成前驗證閘門，強制要求提供新鮮的驗證證據才能宣稱完成。當 agent 或使用者聲稱「完成了」「修好了」「做好了」但未提供驗證證據時自動啟用。不適用於設計討論（用 design-brainstorm）或分支決策（用 branch-finisher）。
allowed-tools: Read, Bash, Grep, Glob
---

# Verification Gate — 完成前驗證閘門

借鑑 obra/superpowers 的 `verification-before-completion` 概念，適配 DD Pipeline 風格。

## 核心原則

**證據優先於宣稱，永遠如此。**

> 沒有新鮮的驗證證據，就不能宣稱完成。
> 執行命令 → 讀取輸出 → 然後才能宣稱結果。

## 鐵律

**禁止在沒有新鮮驗證證據的情況下宣稱完成。**

- 「新鮮」= 在本次工作中實際執行並觀察到的結果
- 「之前跑過」不算 — 程式碼改了，之前的結果已失效
- 「應該可以」不算 — 推測不是證據
- 「改動很小」不算 — 小改動也能破壞系統

## 觸發條件

**自動觸發時機：**
當出現以下宣稱但缺乏對應證據時啟用：

**關鍵詞：**
- 「完成了」「做好了」「修好了」「已修復」
- 「測試通過」「建置成功」「部署完成」
- 「所有功能正常」「問題已解決」
- 「done」「fixed」「all tests pass」

## 5 步驗證流程（閘門函數）

### Step 1: 識別驗證項目

列出所有需要驗證的項目：

| 宣稱類型 | 必要驗證 |
|---------|---------|
| 「測試通過」 | 執行 `npm test` / `pytest` 並讀取輸出 |
| 「建置成功」 | 執行 `npm run build` / `cargo build` 並確認零錯誤 |
| 「bug 已修復」 | 重現原始問題的步驟，確認不再發生 |
| 「功能已實作」 | 執行功能的端對端測試或手動驗證 |
| 「沒有迴歸」 | 執行完整測試套件，確認無新增失敗 |
| 「linting 通過」 | 執行 `eslint` / `ruff` 並確認零警告 |
| 「型別正確」 | 執行 `tsc --noEmit` / `mypy` 並確認零錯誤 |

### Step 2: 執行驗證命令

對每個驗證項目：
1. 執行對應的命令
2. **等待命令完成**（不要假設結果）
3. 記錄完整輸出

### Step 3: 讀取並分析輸出

- 逐行讀取命令輸出
- 識別成功/失敗指標
- 記錄任何警告或異常

### Step 4: 驗證結果

- 所有驗證項目都通過？→ 進入 Step 5
- 有任何失敗？→ **停止，修復問題，重新從 Step 1 開始**
- 有警告但不影響功能？→ 記錄警告，進入 Step 5

### Step 5: 宣稱完成（附帶證據）

產出驗證報告：

```markdown
## 驗證結果

| 項目 | 命令 | 結果 | 證據 |
|-----|------|------|------|
| 測試 | `npm test` | 通過 (25/25) | [輸出摘要] |
| 建置 | `npm run build` | 成功 | 零錯誤，bundle size: 245KB |
| Lint | `eslint .` | 通過 | 零警告 |

**結論**：所有驗證通過，工作已完成。
```

---

## 常見失敗模式

| 宣稱 | 問題 | 正確做法 |
|------|------|---------|
| 「測試應該會通過」 | 沒有實際執行 | 執行測試，讀取輸出 |
| 「我剛才跑過了」 | 在修改後沒有重新執行 | 每次修改後重新驗證 |
| 「改動太小不會有問題」 | 假設小改動無風險 | 小改動也要驗證 |
| 「其他測試不受影響」 | 沒有執行完整測試套件 | 執行所有相關測試 |
| 「本地跑得好好的」 | 環境差異 | 確認 CI 也通過 |

## 紅旗清單 — 看到這些就停下

以下任何情況出現時，**立即停止並補充驗證**：

- 使用「應該」「大概」「我覺得」等不確定語氣
- 跳過測試因為「改動很小」
- 宣稱完成但沒有貼出任何命令輸出
- 引用舊的測試結果（修改前的）
- 說「手動驗證過了」但沒有說明步驟
- 假設 subagent 的工作是正確的而未確認

## 合理化防範

| 常見藉口 | 現實 |
|---------|------|
| 「這只是重構，不影響行為」 | 重構是最常引入 bug 的操作之一 |
| 「型別系統已經保證了」 | 型別不能保證運行時行為 |
| 「我很確定」 | 確定程度不能替代證據 |
| 「時間不夠跑測試」 | 不跑測試花的時間更多（debug） |
| 「測試太慢了」 | 至少跑相關的測試子集 |

## 關鍵驗證模式

### 測試驗證
```bash
# 不要只看 exit code，讀取完整輸出
npm test 2>&1
# 確認：通過數、失敗數、跳過數
```

### 迴歸測試
```bash
# 先確認修改前的失敗
git stash && npm test  # 看到失敗
git stash pop && npm test  # 看到通過
```

### 建置驗證
```bash
npm run build 2>&1
# 確認：零錯誤、零警告、輸出檔案存在
```

### 需求驗證
```markdown
逐條對照需求清單：
- [ ] 需求 1: [具體驗證方式和結果]
- [ ] 需求 2: [具體驗證方式和結果]
```

### Agent 委託驗證
```markdown
subagent 回報完成後：
1. 讀取 subagent 修改的檔案
2. 執行 subagent 聲稱通過的測試
3. 確認結果一致
```

## 與原生 `/goal` 的關係

Claude Code 原生 `/goal` 指令(≥ 2.1.139)與本閘門互補,職責分工:

| 機制 | 負責 |
|------|------|
| `/goal` | **推進跨輪迴圈** — 設定完成條件,未達成就自動再跑一輪 |
| `verification-gate` | **把守每輪證據門檻** — 每次「完成」宣稱都必須附新鮮驗證證據 |

組合使用:用 `/goal` 自主收斂時,本閘門的鐵律仍適用於迴圈中的**每一輪** —— `/goal` 的
評估器讀到的「完成」宣稱,必須是執行命令、讀取輸出後得出的結果,否則就是無證據宣稱,
閘門應擋下。`/goal` 解決「要不要再跑一輪」,`verification-gate` 解決「這一輪能不能說完成」。

## 適用範圍

**何時啟用此閘門：**
- 宣稱 bug 已修復
- 宣稱功能已實作
- 宣稱測試已通過
- 宣稱建置已成功
- 宣稱重構未影響行為
- subagent 回報工作完成

**何時不需要：**
- 純粹的討論或設計（沒有「完成」的宣稱）
- 文件撰寫（無需執行驗證）
- 探索性調查（還在了解問題）

## 底線

**執行命令。讀取輸出。然後才能宣稱結果。**

沒有捷徑。沒有例外。沒有「這次不需要」。