verification-before-completion

Tổng quan về skill verification-before-completion

verification-before-completion dùng để làm gì

Skill verification-before-completion là một quy trình kiểm tra cuối cùng rất chặt chẽ, dùng cho thời điểm bạn sắp nói rằng công việc đã xong, đã sửa xong, đã pass, hoặc đã sẵn sàng để review. Nhiệm vụ của skill này rất đơn giản: chặn các tuyên bố thành công không có căn cứ và buộc phải có bằng chứng mới trước.

Nó đặc biệt hữu ích trong lập trình có AI hỗ trợ, workflow dùng agent, chuẩn bị commit và bàn giao PR. Nếu bạn từng thấy các câu như “tests should pass”, “the bug is fixed” hoặc “build looks good” được nói ra mà chưa thật sự chạy đúng lệnh để kiểm chứng, thì skill này nhắm đúng vào kiểu lỗi đó.

Ai nên cài skill này

Những nhóm người dùng phù hợp nhất gồm có:

• lập trình viên dùng AI agents để chỉnh sửa code
• reviewer muốn các cập nhật trạng thái gọn gàng hơn và có bằng chứng đi kèm
• team đã mệt với các thông báo hoàn thành quá lạc quan nhưng chưa được kiểm chứng
• bất kỳ ai dùng các mẫu Skill Validation, nơi bằng chứng quan trọng hơn sự tự tin

Nếu nhu cầu chính của bạn là sinh code, lập kế hoạch hoặc hỗ trợ debug diện rộng, thì đây không phải skill thay thế cho các nhu cầu đó. Skill verification-before-completion là một hàng rào an toàn, không phải một workflow giao việc hoàn chỉnh.

Công việc thực sự cần giải quyết

Công việc thực sự không phải là “chạy test”. Mà là:

1. xác định loại bằng chứng nào sẽ chứng minh được tuyên bố đó
2. chạy đúng bước kiểm chứng đó ngay bây giờ
3. đọc đầu ra thực tế
4. chỉ đưa ra kết luận đúng với mức bằng chứng đang có

Nghe có vẻ hiển nhiên, nhưng đây chính là chỗ rất nhiều workflow có AI hỗ trợ bị hỏng. Skill này biến kỳ vọng đó thành một cổng chặn cứng trước khi bạn dùng ngôn ngữ kiểu “đã xong”.

Điều gì làm skill này khác biệt

Điểm khác biệt cốt lõi nằm ở sự tập trung hẹp. verification-before-completion không cố “thông minh” trên toàn bộ repository của bạn. Nó chỉ cưỡng chế một quy tắc giá trị cao:

không được tuyên bố hoàn thành nếu không có bằng chứng kiểm chứng mới

Vì thế, nó đặc biệt phù hợp như một skill lớp cuối. So với các prompt kiểu “hãy cẩn thận và kiểm tra trước”, skill này dễ kích hoạt nhất quán hơn vì nó đưa ra một hàm quyết định có thể lặp lại: xác định, chạy, đọc, xác minh, rồi mới phát biểu.

Khi nào verification-before-completion đặc biệt phù hợp

Hãy dùng skill verification-before-completion khi bạn sắp nói những câu như:

• “tests pass”
• “the bug is fixed”
• “the build succeeds”
• “this is ready to merge”
• “the linter is clean”

Mỗi tuyên bố như vậy cần một loại bằng chứng khác nhau. Skill này giúp ngăn một lỗi rất phổ biến: chứng minh được một thứ có liên quan, rồi lại phát biểu quá đà về kết quả.

Cách dùng skill verification-before-completion

Bối cảnh cài đặt cho verification-before-completion

Cài từ repository obra/superpowers:

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

Vì skill này nằm gọn trong một file SKILL.md, việc áp dụng khá nhẹ. Không có helper script hay file tài nguyên bổ sung nào mà bạn phải hiểu trước.

Hãy đọc file này trước

Bắt đầu với:

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

File này chứa toàn bộ “hợp đồng hành vi” của skill. Vì cấu trúc hỗ trợ trong repository ở đây là tối giản, chỉ cần đọc SKILL.md trước là đủ để biết skill có hợp workflow của bạn hay không.

Skill cần bạn cung cấp những đầu vào gì

Skill verification-before-completion hoạt động tốt nhất khi bạn cung cấp ba thứ:

• tuyên bố mà bạn sắp đưa ra
• lệnh thực sự có thể chứng minh tuyên bố đó
• mọi giới hạn môi trường đang chặn việc kiểm chứng

Ví dụ đầu vào:

• “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.”

Nếu không có tuyên bố cụ thể và lệnh cụ thể, skill chỉ có thể đưa ra cảnh báo chung chung.

Biến một mục tiêu mơ hồ thành prompt dùng được

Prompt yếu:

• “Can I say this is done?”

Prompt tốt hơn:

• “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.”

Vì sao cách này tốt hơn:

• nó nêu rõ tuyên bố
• nó đề xuất đường kiểm chứng
• nó cho phép skill phản biện nếu bước kiểm chứng còn quá yếu

Cách gọi skill trong thực tế

Hãy dùng verification-before-completion ngay trước mọi thông điệp kiểu hoàn thành, phần tóm tắt commit hoặc ghi chú PR. Một workflow thực tế là:

1. hoàn tất thay đổi trong code
2. xác định chính xác câu bạn muốn phát biểu
3. xác định lệnh nào chứng minh được câu đó
4. chạy lại đầy đủ lệnh đó trên trạng thái hiện tại
5. kiểm tra output và exit status
6. hạ mức hoặc thêm điều kiện cho tuyên bố nếu bằng chứng chưa đủ

Thứ tự này rất quan trọng. Skill này có giá trị nhất đúng ở thời điểm con người dễ tóm tắt một cách lạc quan.

Ghép đúng tuyên bố với đúng bằng chứng

Một lợi ích thực tế rất lớn của skill verification-before-completion là nó ngăn tình trạng lệch giữa tuyên bố và bằng chứng.

Ví dụ:

• Tuyên bố: “Tests pass”
  Bằng chứng: chạy đầy đủ lệnh test liên quan và có zero failures

• Tuyên bố: “Linter is clean”
  Bằng chứng: lệnh linter cho ra zero errors

• Tuyên bố: “Build succeeds”
  Bằng chứng: lệnh build thoát thành công

• Tuyên bố: “Bug is fixed”
  Bằng chứng: một bước kiểm chứng tái hiện đúng đường lỗi ban đầu và giờ đã pass

Linter pass không chứng minh được build thành công. Một file đã được sửa không chứng minh được bug đã hết. Đây chính là điểm mà rất nhiều đầu ra yếu từ agent thường thất bại.

Thế nào được tính là bằng chứng kiểm chứng mới

“Bằng chứng mới” nghĩa là lệnh đã được chạy cho đúng trạng thái hiện tại của công việc, chứ không phải nhớ lại từ một lần thử trước. Trong thực tế, điều đó có nghĩa là:

• không dựa vào output terminal cũ
• không giả định file không đổi thì kết quả cũng không đổi
• không suy diễn thành công từ các tín hiệu gần kề
• không dùng kiểm chứng một phần để nói cho một tuyên bố rộng hơn

Nếu bạn đã sửa code sau lần chạy gần nhất, thì kết quả cũ đã lỗi thời cho mục đích tuyên bố hoàn thành.

Làm gì khi bạn không thể chạy bước kiểm chứng

Đôi khi môi trường chặn việc thực thi: thiếu dependency, không có credential, service không khả dụng, OS không hỗ trợ hoặc thiếu thời gian. Khi đó, đừng đưa ra tuyên bố mạnh hơn mức có thể chứng minh.

Hãy dùng cách diễn đạt dựa trên bằng chứng:

• “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.”

Ngay cả như vậy, việc dùng verification-before-completion vẫn được xem là thành công, vì mục tiêu của skill là báo cáo trạng thái trung thực chứ không phải ép cho ra một mức chắc chắn giả tạo.

Mẫu prompt thực tế cho agent

Một prompt tái sử dụng tốt:

“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.”

Mẫu này hoạt động tốt trong instruction cho agent, trợ lý PR và các luồng sinh commit message.

Workflow tốt nhất cho các use case Skill Validation

Với verification-before-completion for Skill Validation, hãy coi skill này là bộ xác thực cuối cùng, không phải worker chính. Một trình tự tốt là:

1. dùng một skill khác để implement hoặc debug
2. chuyển sang verification-before-completion
3. kiểm chứng tuyên bố hẹp mà bạn chuẩn bị công bố
4. tạo phần tóm tắt kèm lệnh đã chạy và bằng chứng kết quả

Sự tách bạch này làm tăng độ tin cậy vì phần triển khai và phần xác thực không bị trộn lẫn với nhau.

Câu hỏi thường gặp về skill verification-before-completion

verification-before-completion có chỉ là lời nhắc chạy test không?

Không. Skill verification-before-completion nghiêm ngặt hơn một lời nhắc. Nó cưỡng chế việc ánh xạ giữa tuyên bố và bằng chứng. Mục tiêu không chỉ là “chạy đại một thứ gì đó”, mà là “chạy đúng lệnh chứng minh chính xác điều bạn sắp nói”.

Skill này có hữu ích cho người mới bắt đầu không?

Có, đặc biệt hữu ích với người mới, khi họ vẫn đang học xem mỗi loại kiểm tra thật ra chứng minh được điều gì. Skill này rèn một thói quen rất tốt: đừng khái quát vượt quá bằng chứng mình có. Thói quen đó cải thiện cả độ chính xác kỹ thuật lẫn niềm tin từ reviewer.

Khi nào tôi không nên dùng verification-before-completion?

Đừng dùng nó như skill duy nhất để code hoặc debug. Nó sẽ không thiết kế kiến trúc, truy ra root cause hay tự viết cho bạn một test plan hoàn chỉnh. Đây là một checkpoint ở cuối quy trình, phù hợp nhất khi đi kèm các skill thiên về triển khai.

Nó tốt hơn prompt thông thường ở điểm nào?

Prompt thông thường thường nói “hãy kiểm tra trước khi trả lời”, nhưng agent vẫn dễ trôi sang các tuyên bố mềm, thiếu căn cứ. verification-before-completion skill tốt hơn khi bạn muốn có một cổng chặn nhất quán trước lúc kết luận, với hệ quả rõ ràng cho các khẳng định không có đủ bằng chứng.

Có yêu cầu stack hoặc toolchain cụ thể không?

Không. Skill này không phụ thuộc stack vì logic của nó xoay quanh bằng chứng, không phụ thuộc ngôn ngữ hay framework. Bạn tự cung cấp lệnh chứng minh phù hợp với môi trường của mình, चाहे là pytest, npm test, go test, cargo test, hay công cụ xác minh khác.

Tôi có thể dùng nó khi việc kiểm chứng đầy đủ quá tốn kém không?

Có, nhưng khi đó tuyên bố của bạn cũng phải thu hẹp tương ứng. Nếu bạn chỉ chạy một test có mục tiêu cụ thể, hãy nói rõ test đó đã pass. Đừng nâng nó thành “mọi thứ đều pass” trừ khi bạn đã chạy bước chứng minh rộng hơn.

Cách cải thiện skill verification-before-completion

Nêu rõ tuyên bố trước khi yêu cầu xác thực

Cải thiện lớn nhất về chất lượng đầu ra là nói rõ chính xác câu mà bạn đang định viết. Ví dụ:

• yếu: “validate this”
• mạnh: “I want to say: ‘the payment bug is fixed and tests pass’”

Cách này giúp skill tách các tuyên bố ghép và gán bằng chứng phù hợp cho từng phần.

Chỉ rõ lệnh chứng minh tốt nhất

Đừng bắt skill phải đoán quy ước repository của bạn nếu bạn đã biết sẵn. Đầu vào mạnh hơn là:

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

Điều này giúp giảm sự tự tin sai dựa trên các bước kiểm tra chưa đầy đủ.

Tách trạng thái đã triển khai khỏi trạng thái đã xác minh

Một kiểu lỗi phổ biến là trộn lẫn “tôi đã sửa code” với “vấn đề đã được giải quyết”. Để cải thiện verification-before-completion usage, hãy yêu cầu phản hồi theo hai phần:

• những gì đã thay đổi
• những gì thật sự đã được kiểm chứng

Cách này giữ cho phần tóm tắt trung thực ngay cả khi môi trường không cho phép chạy kiểm chứng.

Tránh tuyên bố rộng từ kiểm tra hẹp

Nếu bạn chỉ chạy một test tập trung, đừng yêu cầu skill chứng nhận cho cả repository. Cách diễn đạt tốt hơn là:

• “Can I say the targeted regression test now passes?”
• không phải “Can I say the system is fully fixed?”

Đây là một trong những thói quen giá trị nhất mà skill này khuyến khích.

Yêu cầu cách hạ mức diễn đạt khi bằng chứng chưa đủ

Một cách thực tế để cải thiện verification-before-completion guide trong công việc hàng ngày là yêu cầu sẵn câu chữ dự phòng:

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

Cách này biến skill thành công cụ nâng chất lượng giao tiếp, chứ không chỉ là một bộ chặn.

Chạy lại sau những thay đổi đáng kể

Nếu bạn sửa code sau một lần kiểm chứng thành công, hãy dùng lại skill verification-before-completion. Bằng chứng mới luôn gắn với trạng thái hiện tại, không phải bản nháp trước đó. Điều này đặc biệt quan trọng trong các vòng lặp agent nhanh, nơi một “chỉnh sửa nhỏ cuối cùng” cũng có thể làm mất hiệu lực các kiểm tra trước đó.

Đưa bằng chứng vào phần tóm tắt cuối

Để tăng độ tin cậy, hãy đưa trực tiếp bằng chứng vào ghi chú hoàn thành:

• lệnh đã chạy
• kết quả pass/fail
• mọi giới hạn hoặc phần còn thiếu

Ví dụ:

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

Kiểu trình bày này làm cho skill có giá trị hơn với reviewer và cả chính bạn về sau.

Chú ý kiểu lỗi phổ biến nhất

Cách dùng sai phổ biến nhất của verification-before-completion for Skill Validation là tuyên bố thành công dựa trên ý định, thay đổi code hoặc kỳ vọng, thay vì dựa trên output thực tế. Nếu muốn kết quả tốt hơn, hãy tự hỏi một câu cuối cùng trước mọi thông điệp hoàn thành:

“What command output would make this statement true?”

Nếu bạn không thể trả lời rõ ràng, rất có thể tuyên bố đó vẫn chưa sẵn sàng.