verification-before-completion

概觀

什麼是 verification-before-completion 技能？

verification-before-completion 技能為開發者與代理（agents）定義了一條嚴格的工作流程規則：除非你剛剛真正執行了相關的驗證指令並檢視其輸出，否則不得說工作已完成、測試已通過，或錯誤已修復。核心原則是：

先有證據，才有主張，而且永遠如此。

在實務上，這代表在你寫下「tests are passing」、「the build is green」或「the bug is fixed」之前，你必須：

• 找出能證明此主張的指令
• 重新實際執行該指令（不能依賴舊的執行結果或主觀推測）
• 讀取輸出內容與結束狀態（exit status）
• 之後才能根據這些證據陳述結果

適合哪些人使用這個技能？

在以下情況，可考慮使用 verification-before-completion 技能：

• 你所在的程式碼庫經常出現測試沒過、建置失敗或修補未驗證就被放行的狀況
• 你依賴的代理或自動化工具，可能會在沒有實際執行檢查的情況下就宣稱成功
• 你希望在開發流程中建立一套有紀律、可重複的測試與驗證作法

特別適用於：

• 測試自動化：確保測試套件真的有被執行，且結果被正確解讀
• 工作流程自動化：強制所有「完成」步驟一定要包含驗證指令
• 進行程式碼審查、CI、CD 的團隊，希望在「標記為完成」後減少意外狀況

verification-before-completion 解決什麼問題？

在沒有防護機制的情況下，很容易：

• 因為變更「很小」就想當然認為測試會通過
• 只因修改了程式碼，就宣稱 bug 已修復，卻沒有重新執行原本失敗的情境
• 依賴舊的成功建置，而不是在修改後重新建置

verification-before-completion 技能將這個規則定義為此 repo 中的 Iron Law：

NO COMPLETION CLAIMS WITHOUT FRESH VERIFICATION EVIDENCE

採用這個技能後，你會把這條鐵律具體化成你自己、你的團隊或你的代理必須遵守的明確工作流程規則。這有助於減少：

• Pull request 中不實的「綠燈」宣稱
• 從未實際測到的隱性回歸（regressions）
• 開發者、審查者與自動化系統之間的溝通落差

什麼時候適合導入這個技能？

在以下情況，verification-before-completion 很適合：

• 專案已經有 test、lint 或 build 指令，你希望確保它們在每次宣稱完成前都會被執行
• 你使用代理或腳本協助開發工作，需要它們在驗證這件事上非常嚴謹
• 相較於節省幾秒鐘的流程時間，你更在意狀態回報的可靠度

在以下情況，可能沒那麼有幫助：

• 專案目前還沒有任何具意義的自動檢查（沒有 tests、沒有 lints、沒有 build 指令）
• 你正在做探索性開發，暫時還不打算對「已通過」或「已修復」做出明確宣稱
• 你只是把這個 repo 當成概念參考，而不是要直接套用它的流程規範

在這些情境下，你仍然可以把這個技能當成未來設計測試與檢查機制時的參考指引。

使用方式

安裝與設定

透過 npx 安裝 verification-before-completion 技能：

npx skills add https://github.com/obra/superpowers --skill verification-before-completion

安裝完成後：

1. 開啟 obra/superpowers repository 裡的 skills/verification-before-completion 目錄。
2. 先從 SKILL.md 開始閱讀，了解完整規則與設計理由。
3. 將這條規則整合進你自己專案的文件、代理設定或開發指引中。

你不需要完全複製該 repository 的目錄結構，而是把它當成參考範本，思考如何在你的環境中描述並落實這項規則。

核心流程：Gate Function

這個技能定義了一個必須在任何「完成宣稱」之前執行的 Gate Function。在日常工作中可以這樣套用：

BEFORE claiming any status or expressing satisfaction:

1. IDENTIFY: What command proves this claim?
2. RUN: Execute the FULL command (fresh, complete)
3. READ: Full output, check exit code, count failures
4. VERIFY: Does output confirm the claim?
   - If NO: State actual status with evidence
   - If YES: State claim WITH evidence
5. ONLY THEN: Make the claim

只要跳過其中任何一步，就不再符合 verification-before-completion 的要求。

常見指令類型範例：

• 測試：npm test、pytest、go test ./...、mvn test
• Lint：eslint .、flake8、golangci-lint run
• 建置：npm run build、make、cargo build --release
• 針對特定 bug 的驗證：能重現原問題的特定 script、test 或手動檢查流程

範例：在開發流程中使用這個技能

情境： 你更新了程式碼，想要宣稱「All tests pass」。

套用 verification-before-completion：

1. IDENTIFY 指令：例如 pytest。
2. 在變更後 RUN 該指令：

   pytest
   

3. READ 輸出並確認 exit code 為 0。
4. VERIFY：
   • 若測試失敗，請不要宣稱成功，而是回報類似：「Tests are failing：test_user_flow.py 中有 3 個測試失敗。詳見 pytest 輸出。」
   • 若測試通過，可以宣稱：「All tests pass (pytest, exit code 0).」
5. ONLY THEN 才將任務標記為完成、推送 commits 或開 Pull request。

這個模式也同樣適用於所有狀態類型的主張：建置、linters、程式碼格式化或 bug 修復等。

與代理與自動化整合

如果你使用協助開發工作的代理或腳本：

• 將它們設定為：任何與測試、建置或修復相關的成功宣稱，都必須先有實際執行過的指令與輸出摘要。
• 要求代理明確列出執行過的指令與結果，例如：
  • 「Ran npm test: exit code 0, 0 failing tests.」
  • 「Ran npm run build: exit code 1, build failed. Not claiming completion.」

在 code review 或 CI pipeline 中，只要是沒有證據支撐的主張，都可以依照 verification-before-completion 視為不完整。

依照你的工具與環境調整

這個 repository 不強制使用特定語言或框架。你可以這樣調整這項技能：

• 將每一種常見的完成宣稱對應到一個單一且明確的指令，用來驗證該主張。
• 在你的 repo 中文件化這些對應關係（例如寫在 CONTRIBUTING.md 或 WORKFLOW.md）。
• 鼓勵或要求貢獻者與代理務必：
  • 在說「done」之前先執行這些指令
  • 在做出主張時貼上或摘要相關輸出內容

主張與指令對應關係範例：

• 「Backend tests pass」 → pytest backend/tests
• 「Frontend builds successfully」 → 在 frontend/ 中執行 npm run build
• 「Go module is clean」 → go test ./... 與 golangci-lint run

常見問題（FAQ）

verification-before-completion 的主要規則是什麼？

主要規則就是這條「Iron Law」：

NO COMPLETION CLAIMS WITHOUT FRESH VERIFICATION EVIDENCE

如果你沒有剛剛執行過相關驗證指令並檢視其輸出，就無法誠實地宣稱自己已經成功完成。

什麼算是「verification evidence」？

Verification evidence 指的是能直接驗證你主張的最新輸出結果，例如：

• 測試套件執行結果顯示 0 個失敗，且 exit code 為 0
• Linter 執行結果沒有錯誤，且結束狀態為成功
• 建置指令成功完成（exit 0）
• 用來重現某個 bug 的 script 或 test 現在通過了

舊的結果、主觀推測，或「理論上應該會動」在這個技能下都不算證據。

如果程式碼沒變，我可以依賴之前的測試結果嗎？

在 verification-before-completion 的預設立場下是 不建議 的。這個技能強調的是：每一次新的完成宣稱之前，都應該進行一次全新的驗證。如果你真的要依賴先前的結果，就必須非常明確且謹慎地界定在什麼條件下這樣是可接受的，並理解這會削弱你給出的保證力道。

這個技能是否依賴特定工具或程式語言？

不會。verification-before-completion 是工具無關的，只要你的技術堆疊能：

• 定義用來驗證行為的指令（tests、linters、builds、scripts）
• 需要時可以隨時執行
• 能解讀它們的 exit code 與輸出內容

你只需要填入對你專案而言相關的指令，並遵守 Gate Function 的步驟即可。

這和「偶爾跑一下測試」有什麼不同？

差別在於紀律與一致性：

• 在每一次宣稱完成之前，你都會執行驗證指令。
• 你每次都會閱讀輸出，而不是直接假設成功。
• 你會把任何沒有證據支撐的主張視為無效。

這會讓測試與建置執行真正成為流程中的一道正式「閘門」，而不是可有可無的附加步驟。

verification-before-completion 適用於手動測試嗎？

適用，只要你能定義一套清楚的流程，讓它在概念上扮演一個「指令」的角色。例如：

• 撰寫一套可以重現 bug 的逐步手動測試流程
• 在修改後重新執行這些步驟
• 將結果紀錄下來作為證據

不過，這個技能在驗證能透過 script 或測試框架自動化時效果最好，因為這樣結果可重複且容易重新執行。

哪裡可以看到原始的技能定義？

verification-before-completion 技能的權威說明位於 obra/superpowers repository 中的 SKILL.md 檔案：

• Repository: https://github.com/obra/superpowers
• Skill file: skills/verification-before-completion/SKILL.md

如需原始原則描述、Iron Law、Gate Function 的完整文字，以及常見錯誤示例，請參考該檔案。