verification-before-completion

verification-before-completion 技能總覽

verification-before-completion 是做什麼用的

verification-before-completion 技能是一套嚴格的最後確認流程，專門用在你正準備說工作「完成了」、「修好了」、「測試通過了」或「可以送審了」的那一刻。它的任務很單純：先阻止沒有根據的成功宣告，要求先拿到最新驗證證據再說。

這個技能特別適合用在 AI 輔助寫程式、agent 工作流程、準備 commit，以及 PR 交接的情境。如果你曾看過有人在根本沒跑對應指令的情況下，就寫出「tests should pass」、「the bug is fixed」或「build looks good」，那 verification-before-completion 正是用來處理這種失誤模式。

誰適合安裝這個技能

最適合的使用者包括：

• 使用 AI agents 修改程式碼的開發者
• 希望狀態更新更乾淨、且有證據支撐的 reviewer
• 已經受夠過度樂觀、卻沒有驗證依據完成訊息的團隊
• 採用 Skill Validation 模式，且把證明看得比信心更重要的人

如果你主要需要的是程式碼生成、規劃，或廣泛的除錯協助，那這個技能不能取代那些用途。verification-before-completion 是一道防護欄，不是完整的交付流程。

真正要完成的工作是什麼

真正的工作不是「跑測試」而已，而是：

1. 先辨認出什麼證據才能證明這個說法成立
2. 立刻跑那個精確的驗證
3. 讀取實際輸出結果
4. 只說出證據真正支持的內容

這聽起來很理所當然，但很多 AI 輔助工作流程正是卡在這裡。verification-before-completion 把這個期待變成完成宣告前的一道硬性關卡。

這個技能有什麼不同

verification-before-completion 最大的差異，在於它非常聚焦。它不試圖聰明地理解你整個 repository，而是只強制執行一條高價值規則：

沒有最新的驗證證據，就不能做完成宣告

正因為它夠窄、夠明確，所以特別適合作為收尾階段的技能。和一般「小心一點、記得驗證」這類 prompt 相比，verification-before-completion 更容易穩定觸發，因為它提供的是一個可重複執行的判斷流程：先辨認、再執行、再閱讀、再驗證，最後才發言。

什麼情況下 verification-before-completion 特別適合

當你準備說出下列這種話時，就很適合使用 verification-before-completion：

• 「tests pass」
• 「the bug is fixed」
• 「the build succeeds」
• 「this is ready to merge」
• 「the linter is clean」

這些說法各自需要不同的證據。verification-before-completion 可以幫你避免一個很常見的錯誤：明明只證明了相鄰的事情，最後卻把結論說得更大。

如何使用 verification-before-completion 技能

verification-before-completion 的安裝情境

請從 obra/superpowers repository 安裝：

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

由於這個技能只包含在單一的 SKILL.md 中，導入成本很低。你不需要先理解輔助腳本，也沒有額外的資源檔案要先看。

先讀這個檔案

從這裡開始：

• skills/verification-before-completion/SKILL.md

這個檔案就包含了完整的行為契約。由於這個技能的 repository 支援結構非常精簡，先讀 SKILL.md 就足以判斷它是否符合你的工作流程。

這個技能需要你提供哪些輸入

verification-before-completion 在你提供以下三項資訊時效果最好：

• 你正準備提出的主張
• 真正能證明該主張的指令
• 任何阻礙驗證的環境限制

輸入範例：

• 「I want to say the fix works. The proving command is pytest tests/api/test_login.py -q.」
• 「I want to say the build passes. The expected verification is npm run build.」
• 「I think lint is clean, but I have not run ruff check . yet.」

如果沒有明確的主張和具體指令，verification-before-completion 只能給你比較泛泛的提醒。

把模糊目標改寫成可用的 prompt

弱的 prompt：

• 「Can I say this is done?」

更好的 prompt：

• 「Before I claim this is complete, apply the verification-before-completion skill. The claim is: ‘the login bug is fixed.’ The best proving command is pytest tests/auth/test_login_bug.py -q. If that is not enough, tell me what additional verification is required.」

為什麼這樣比較好：

• 它明確指出了主張內容
• 它先提出了一條可驗證的證明路徑
• 它允許技能挑戰證據不足的驗證方式

實務上怎麼呼叫這個技能

在任何完成式訊息、commit 摘要或 PR 說明之前，先用 verification-before-completion。一個實用的流程如下：

1. 完成程式碼修改
2. 決定你要提出的精確主張是什麼
3. 找出能證明該主張的指令
4. 重新完整執行一次那個指令
5. 檢查輸出內容與 exit status
6. 如果證據不完整，就下修或加註限定條件

這個順序很重要。人在最想樂觀總結的那一刻，verification-before-completion 的價值最高。

讓主張對應到正確證據

verification-before-completion 在實務上最大的好處之一，就是阻止「證據和主張對不起來」的情況。

例如：

• 主張：「Tests pass」
  證據：對應的完整測試指令，且零失敗

• 主張：「Linter is clean」
  證據：linter 指令輸出顯示零錯誤

• 主張：「Build succeeds」
  證據：build 指令成功結束

• 主張：「Bug is fixed」
  證據：能重現原始失敗路徑的驗證步驟，且現在已通過

linter 通過，不能證明 build 一定成功。檔案改過了，也不能證明 bug 已修好。這種區分正是很多弱 agent 輸出會失手的地方。

什麼才算最新的驗證證據

所謂最新，指的是這個指令是針對目前這個工作狀態執行的，不是憑前一次的記憶帶過。實務上代表：

• 不依賴舊的 terminal 輸出
• 不假設檔案沒變、結果就一定沒變
• 不從旁邊的訊號推論成功
• 不用局部驗證去支撐更大的主張

如果你在上一次執行後又改了程式碼，那對於完成宣告來說，先前那次執行就已經過期了。

無法執行驗證時該怎麼做

有時候環境就是不允許你執行：可能缺少 dependencies、沒有 credentials、服務不可用、作業系統不支援，或時間不夠。這種情況下，就不要做更強的主張。

請改用以證據為基礎的描述：

• 「I made the change, but I could not run npm test in this environment.」
• 「The fix is implemented, but build verification remains unconfirmed.」
• 「I verified formatting only; full integration tests were not run.」

即使是這樣，verification-before-completion 仍然算是成功使用了，因為它的重點是誠實回報狀態，而不是硬湊出確定性。

給 agents 的實用 prompt 模式

一個可重複使用、效果不錯的 prompt：

「Use the verification-before-completion skill before any success claim. For each claim, identify the proving command, run it fresh if possible, read the full output, and only state what the evidence confirms. If verification is blocked, report the limitation instead of implying success.」

這種寫法很適合放進 agent 指示、PR 助手，以及 commit 產生流程中。

Skill Validation 情境下的最佳工作流程

針對 verification-before-completion for Skill Validation，請把它當成最後的驗證者，而不是主要執行者。比較好的順序是：

1. 先用其他技能完成實作或除錯
2. 再切換到 verification-before-completion
3. 驗證你準備對外發布的狹義主張
4. 產出附帶指令與結果證據的摘要

這種分工能提高信任感，因為實作和驗證沒有混在一起。

verification-before-completion 技能 FAQ

verification-before-completion 只是提醒你記得跑測試嗎？

不是。verification-before-completion 比單純提醒更嚴格。它要求主張和證明之間要有明確對應。重點不是只是「跑點什麼」，而是「執行能證明你即將說出口那句話的那個指令」。

這個技能對新手有用嗎？

有，尤其適合還在學習「不同檢查到底能證明什麼」的新手。它會培養一個很重要的習慣：不要把結論講得超出證據範圍。這個習慣同時能提升技術準確度，也能增加 reviewer 對你的信任。

什麼情況下不該使用 verification-before-completion？

不要把它當成你唯一的寫程式或除錯技能。它不會幫你設計架構、定位根因，也不會替你寫完整測試計畫。verification-before-completion 比較像收尾檢查點，最適合和偏實作導向的技能搭配使用。

它比一般 prompt 好在哪裡？

一般 prompt 常常只會說「回答前先驗證」，但 agent 還是很容易滑向模糊、偏軟的主張。如果你要的是一個穩定的完成前關卡，並且對沒有根據的斷言有明確後果，那 verification-before-completion skill 會比普通 prompt 更好用。

它需要特定技術棧或工具鏈嗎？

不需要。verification-before-completion 是 stack-agnostic，因為它關心的是證據邏輯，不是程式語言或 framework。你只需要提供符合自己環境的證明指令，不管那是 pytest、npm test、go test、cargo test，還是其他驗證工具都可以。

如果完整驗證成本太高，還能用嗎？

可以，但你的主張也必須跟著縮小。如果你只跑了針對性的測試，就只能說那個針對性的測試已通過。除非你真的做了更完整的驗證，否則不要把它升級成「全部都通過」。

如何改進 verification-before-completion 技能的使用效果

在要求驗證前，先把主張講清楚

最能提升輸出品質的一件事，就是直接寫出你差點想貼出去的那一句話。例如：

• 弱：「validate this」
• 強：「I want to say: ‘the payment bug is fixed and tests pass’」

這能幫助 verification-before-completion 把複合主張拆開，並分別配置對應證據。

明確寫出最佳的證明指令

如果你本來就知道 repository 的慣例，就不要讓 verification-before-completion 猜。更好的輸入方式像是：

• 「The canonical project check is make test.」
• 「The bug is proven by pytest tests/payments/test_refund.py -q plus npm run build.」

這樣可以降低因為檢查不完整而產生的錯誤信心。

把實作狀態和已驗證狀態分開

常見失誤之一，是把「我改了程式碼」和「問題已解決」混在一起。想改進 verification-before-completion usage，可以直接要求它用兩段式回覆：

• 改了什麼
• 實際驗證了什麼

即使執行受阻，這也能讓摘要維持誠實。

不要用狹窄檢查去支撐寬泛主張

如果你只跑了一個聚焦測試，就不要要求 verification-before-completion 替整個 repo 背書。比較好的說法是：

• 「Can I say the targeted regression test now passes?」
• 不要說：「Can I say the system is fully fixed?」

這是這個技能最值得養成的高價值習慣之一。

當證據不完整時，要求它提供降級措辭

在真實工作裡，想讓 verification-before-completion guide 更實用，一個很好用的方法是主動要求 fallback wording：

• 「If the claim is too strong for the evidence, rewrite it to the strongest accurate version.」

這樣一來，它就不只是擋下過度宣告的工具，也成了改善溝通品質的工具。

有實質修改後要重新跑一次

如果你在一次成功驗證後又改了程式碼，請再次使用 verification-before-completion。最新證據只對應目前狀態，不對應上一個草稿版本。這在高速 agent loop 裡尤其重要，因為一個「最後的小修改」就可能讓前面的檢查失效。

在最終摘要中直接附上證據

如果想提高信任感，請在完成說明裡直接放入證據：

• 執行了什麼指令
• pass/fail 結果
• 任何限制或遺漏項目

例如：

• 「Verified with pytest tests/auth/test_login_bug.py -q: passed, 1 test, 0 failures.」
• 「Did not verify full integration suite in this environment.」

這種寫法會讓 verification-before-completion 對 reviewer 和未來的自己都更有價值。

留意最常見的失敗模式

verification-before-completion for Skill Validation 最常見的誤用，是根據意圖、程式碼變更，或主觀預期來宣稱成功，而不是根據實際輸出。如果你想得到更好的結果，請在每次完成訊息前最後問自己一次：

「What command output would make this statement true?」

如果你沒辦法清楚回答，那這個主張大概還沒準備好。