verification-before-completion

Visão geral da skill verification-before-completion

Para que serve a verification-before-completion

A skill verification-before-completion é um fluxo rígido de checagem final para os momentos em que você está prestes a dizer que algo está concluído, corrigido, passando ou pronto para revisão. A função dela é simples: impedir alegações de sucesso sem respaldo e exigir evidência nova antes de qualquer afirmação.

Isso é especialmente útil em coding com apoio de IA, fluxos com agentes, preparação de commits e handoff de PR. Se você já viu frases como “tests should pass”, “the bug is fixed” ou “build looks good” sem que o comando certo tenha sido realmente executado, esta skill ataca exatamente esse tipo de falha.

Quem deve instalar esta skill

Os perfis com melhor aderência incluem:

• desenvolvedores que usam agentes de IA para editar código
• reviewers que querem atualizações de status mais limpas e sustentadas por evidência
• equipes cansadas de mensagens de conclusão otimistas, mas não verificadas
• qualquer pessoa que use padrões de Skill Validation, em que prova importa mais do que confiança

Se o que você quer principalmente é geração de código, planejamento ou ajuda ampla de debugging, esta não substitui essas skills. A verification-before-completion é uma barreira de segurança, não um fluxo completo de entrega.

O trabalho real que ela resolve

O trabalho real não é “rodar testes”. É:

1. identificar qual evidência provaria a afirmação
2. executar agora exatamente essa verificação
3. ler a saída real
4. só então afirmar o que a evidência de fato sustenta

Parece óbvio, mas é exatamente aí que muitos fluxos com IA quebram. A verification-before-completion transforma essa expectativa em um gate rígido antes de qualquer linguagem de conclusão.

O que diferencia esta skill

O principal diferencial é o foco estreito. A verification-before-completion não tenta ser esperta sobre o repositório inteiro. Ela impõe uma regra única e de alto valor:

nenhuma alegação de conclusão sem evidência nova de verificação

Isso faz dela uma ótima skill de camada final. Em comparação com um prompt genérico do tipo “tenha cuidado e verifique”, esta é mais fácil de acionar com consistência porque oferece uma função de decisão repetível: identificar, executar, ler, verificar e só depois falar.

Quando esta skill é uma escolha forte

Use a skill verification-before-completion quando você estiver prestes a dizer coisas como:

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

Cada uma dessas afirmações exige um tipo de evidência. A skill ajuda a evitar um erro muito comum: provar algo adjacente e depois exagerar o resultado.

Como usar a skill verification-before-completion

Contexto de instalação da verification-before-completion

Instale a partir do repositório obra/superpowers:

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

Como esta skill está contida em um único SKILL.md, a adoção é leve. Não há scripts auxiliares nem arquivos extras de recursos para entender antes.

Leia este arquivo primeiro

Comece por:

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

Esse arquivo contém todo o contrato de comportamento. Como a estrutura de suporte no repositório é mínima neste caso, ler o SKILL.md primeiro já basta para entender se a skill combina com o seu fluxo de trabalho.

Que tipo de input a skill precisa de você

A skill verification-before-completion funciona melhor quando você fornece três coisas:

• a afirmação que está prestes a fazer
• o comando que realmente provaria essa afirmação
• quaisquer limitações de ambiente que estejam bloqueando a verificação

Exemplos de input:

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

Sem uma afirmação concreta e um comando concreto, a skill só consegue oferecer cautela genérica.

Transforme um objetivo vago em um prompt útil

Prompt fraco:

• “Can I say this is done?”

Prompt melhor:

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

Por que isso é melhor:

• nomeia a afirmação
• propõe um caminho de prova
• permite que a skill conteste uma verificação fraca ou insuficiente

Como acionar a skill na prática

Use verification-before-completion imediatamente antes de qualquer mensagem de conclusão, resumo de commit ou nota de PR. Um fluxo prático é:

1. terminar a alteração no código
2. decidir qual afirmação exata você quer fazer
3. identificar o comando que prova essa afirmação
4. executar esse comando completo novamente
5. inspecionar a saída e o exit status
6. reduzir ou qualificar a afirmação se a evidência estiver incompleta

Essa sequência importa. A skill é mais valiosa justamente no ponto em que as pessoas ficam tentadas a resumir tudo de forma otimista.

Faça a correspondência certa entre afirmação e prova

Um dos maiores benefícios práticos da skill verification-before-completion é impedir desencontro entre prova e afirmação.

Exemplos:

• Afirmação: “Tests pass”
  Prova: o comando completo de teste relevante, com zero falhas

• Afirmação: “Linter is clean”
  Prova: o comando do linter mostrando zero erros

• Afirmação: “Build succeeds”
  Prova: o comando de build encerrando com sucesso

• Afirmação: “Bug is fixed”
  Prova: uma etapa de verificação que reproduz o caminho original da falha e agora passa

Um linter passando não prova que o build funciona. Um arquivo alterado não prova que um bug foi corrigido. É exatamente nessa distinção que muitos outputs fracos de agentes falham.

O que conta como evidência nova de verificação

“Nova” significa que o comando foi executado para este estado exato do trabalho, e não lembrado de uma tentativa anterior. Na prática, isso significa:

• não confiar em saída antiga de terminal
• não assumir que arquivos inalterados implicam o mesmo resultado
• não inferir sucesso a partir de sinais próximos
• não usar verificação parcial para sustentar uma afirmação mais ampla

Se você mudou o código depois da última execução, aquela execução antiga ficou obsoleta para fins de conclusão.

O que fazer quando você não consegue rodar a verificação

Às vezes o ambiente bloqueia a execução: dependências ausentes, falta de credenciais, serviços indisponíveis, SO não suportado ou restrições de tempo. Nesse caso, não faça a afirmação mais forte.

Use uma linguagem baseada em evidência:

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

Ainda assim, o uso da verification-before-completion foi bem-sucedido, porque a skill trata de reportar status com honestidade, não de forçar certeza.

Padrão de prompt prático para agentes

Um prompt forte e reutilizável:

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

Isso funciona bem em instruções de agentes, assistentes de PR e fluxos de geração de commit.

Melhor fluxo para casos de uso de Skill Validation

Para verification-before-completion for Skill Validation, trate a skill como validadora final, não como a principal responsável pelo trabalho. Uma boa sequência é:

1. usar outra skill para implementar ou depurar
2. mudar para verification-before-completion
3. verificar a afirmação específica que você quer publicar
4. produzir um resumo com o comando e a evidência do resultado

Essa separação aumenta a confiança porque implementação e validação não ficam misturadas.

FAQ da skill verification-before-completion

A verification-before-completion é só um lembrete para rodar testes?

Não. A skill verification-before-completion é mais rígida do que um lembrete. Ela impõe um mapeamento entre afirmação e prova. O ponto não é apenas “rodar alguma coisa”, mas sim “rodar o comando que prova exatamente a frase que você está prestes a dizer”.

Esta skill é útil para iniciantes?

Sim, especialmente para iniciantes que ainda estão aprendendo o que diferentes checks realmente provam. Ela ensina um hábito forte: não generalizar além da sua evidência. Esse hábito melhora tanto a precisão técnica quanto a confiança de reviewers.

Quando eu não devo usar verification-before-completion?

Não use como sua única skill de coding ou debugging. Ela não vai desenhar arquitetura, encontrar causas-raiz nem escrever um plano completo de testes por você. É um checkpoint final, que funciona melhor em conjunto com skills orientadas à implementação.

Por que ela é melhor do que um prompt comum?

Um prompt comum costuma dizer “verifique antes de responder”, mas os agentes ainda escorregam para afirmações vagas ou frouxas. A verification-before-completion skill é melhor quando você quer um gate consistente antes da conclusão, com consequências explícitas para afirmações sem suporte.

Ela exige uma stack ou toolchain específica?

Não. A skill é agnóstica de stack porque sua lógica gira em torno de evidência, não de linguagem ou framework. Você fornece o comando de prova do seu ambiente, seja pytest, npm test, go test, cargo test ou outro verificador.

Posso usar quando a verificação completa é cara demais?

Sim, mas nesse caso sua afirmação também precisa ser mais estreita. Se você rodou apenas um teste direcionado, diga que esse teste direcionado passou. Não eleve isso para “everything passes” a menos que você tenha executado a prova mais ampla.

Como melhorar a skill verification-before-completion

Diga a afirmação antes de pedir validação

A maior melhoria na qualidade da saída é informar a frase exata que você está tentado a escrever. Por exemplo:

• fraco: “validate this”
• forte: “I want to say: ‘the payment bug is fixed and tests pass’”

Isso ajuda a skill a separar afirmações compostas e atribuir uma prova para cada parte.

Nomeie explicitamente o melhor comando de prova

Não faça a skill adivinhar as convenções do seu repositório se você já as conhece. Input mais forte:

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

Isso reduz falsa confiança baseada em checks incompletos.

Separe status de implementação de status verificado

Uma falha comum é misturar “eu alterei o código” com “o problema está resolvido”. Melhore o uso de verification-before-completion pedindo uma resposta em duas partes:

• o que mudou
• o que foi realmente verificado

Isso mantém os resumos honestos mesmo quando a execução está bloqueada.

Evite afirmações amplas com base em checks estreitos

Se você executou um teste focado, não peça para a skill certificar o repositório inteiro. Formulação melhor:

• “Can I say the targeted regression test now passes?”
• não “Can I say the system is fully fixed?”

Este é um dos hábitos de maior valor que a skill incentiva.

Peça linguagem de downgrade quando a evidência for parcial

Uma forma prática de melhorar o verification-before-completion guide no trabalho real é pedir uma redação alternativa de fallback:

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

Isso transforma a skill em uma ferramenta de qualidade de comunicação, não apenas em um bloqueio.

Rode novamente após mudanças materiais

Se você editar o código depois de uma verificação bem-sucedida, use a skill verification-before-completion de novo. Evidência nova está vinculada ao estado atual, não ao rascunho anterior. Isso importa ainda mais em loops rápidos com agentes, em que um “pequeno ajuste final” pode invalidar checks anteriores.

Use a evidência no resumo final

Para gerar mais confiança, inclua a prova diretamente na nota de conclusão:

• comando executado
• resultado de sucesso/falha
• quaisquer limites ou omissões

Exemplo:

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

Esse estilo torna a skill mais valiosa para reviewers e para você no futuro.

Fique atento ao padrão de falha mais comum na verification-before-completion

O uso incorreto mais comum de verification-before-completion for Skill Validation é declarar sucesso com base em intenção, alterações de código ou expectativa, em vez de saída real. Se você quer resultados melhores, faça uma última pergunta antes de cada mensagem de conclusão:

“What command output would make this statement true?”

Se você não consegue responder isso com clareza, provavelmente a afirmação ainda não está pronta.