verification-before-completion

Visão geral

O que é a skill verification-before-completion?

A skill verification-before-completion define uma regra de fluxo de trabalho rígida para desenvolvedores e agentes: nunca diga que o trabalho está concluído, que os testes estão passando ou que um bug foi corrigido sem ter acabado de executar o comando de verificação relevante e checado sua saída. O princípio central é:

Evidência antes das afirmações, sempre.

Na prática, isso significa que, antes de escrever "os testes estão passando", "o build está verde" ou "o bug foi corrigido", você deve:

• Identificar o comando que comprova a afirmação
• Executá-lo na hora (sem confiar em execuções antigas ou suposições)
• Ler a saída e o código de saída (exit status)
• Só então declarar o resultado, sustentado por essa evidência

Para quem é essa skill?

Use a skill verification-before-completion se você:

• Trabalha em bases de código onde testes falhando, builds quebrados ou correções não verificadas escapam com frequência
• Depende de agentes ou ferramentas automatizadas que podem declarar sucesso sem realmente rodar as checagens
• Quer uma prática disciplinada e repetível de testes e verificação como parte do seu fluxo de desenvolvimento

Ela é especialmente relevante para:

• Automação de testes: garantir que suítes de testes sejam de fato executadas e interpretadas corretamente
• Automação de fluxo de trabalho: impor que etapas de conclusão sempre incluam comandos de verificação
• Times que praticam code review, integração contínua e entrega contínua e querem menos surpresas após um status de "feito".

Que problema a verification-before-completion resolve?

Sem um trilho de proteção, é fácil:

• Assumir que os testes vão passar porque a mudança é "pequena"
• Afirmar que um bug foi corrigido após editar o código, sem reexecutar o cenário que falhava
• Confiar em um build anterior bem-sucedido em vez de reconstruir após mudanças

A skill verification-before-completion define o que o repositório chama de Lei de Ferro:

NO COMPLETION CLAIMS WITHOUT FRESH VERIFICATION EVIDENCE

Ao adotar essa skill, você transforma essa lei em uma regra concreta de fluxo de trabalho para você, seu time ou seus agentes. Isso reduz:

• Falsas afirmações de "verde" em pull requests
• Regressões ocultas que nunca foram testadas
• Ruídos e desencontros entre desenvolvedores, revisores e automações

Quando essa skill é uma boa escolha?

Escolha verification-before-completion quando:

• Você já tem comandos de teste, lint ou build disponíveis e quer garantir que sejam sempre executados
• Você usa agentes ou scripts para ajudar em tarefas de desenvolvimento e precisa que sejam rigorosos com verificação
• Você valoriza relatórios de status confiáveis mais do que economizar alguns segundos no fluxo de trabalho

Ela pode ser menos útil se:

• Seu projeto ainda não tem checagens automatizadas significativas (sem testes, sem lints, sem comandos de build)
• Você está fazendo trabalho exploratório e ainda não está pronto para fazer afirmações de "passando" ou "corrigido"
• Você está usando o repositório apenas como referência conceitual, não como um fluxo de trabalho a ser aplicado à risca

Nesses casos, você ainda pode usar a skill como guia para desenhar futuros testes e checagens.

Como usar

Instalação e configuração

Para instalar a skill verification-before-completion via npx:

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

Após a instalação:

1. Abra o diretório skills/verification-before-completion no repositório obra/superpowers.
2. Comece pelo arquivo SKILL.md para ver a regra completa e a justificativa.
3. Integre a regra à documentação do seu projeto, à configuração de agentes ou às diretrizes de desenvolvimento.

Você não precisa copiar exatamente a estrutura do repositório. Use-o como referência de como descrever e aplicar a regra no seu ambiente.

Fluxo de trabalho central: a Gate Function

A skill define uma Gate Function que deve ser executada antes de qualquer afirmação de conclusão. No dia a dia, aplique assim:

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

Se você pular qualquer etapa, já não está seguindo verification-before-completion.

Exemplos de comandos típicos:

• Testes: npm test, pytest, go test ./..., mvn test
• Lint: eslint ., flake8, golangci-lint run
• Build: npm run build, make, cargo build --release
• Verificação direcionada de bug: o script, teste ou check manual específico que reproduz o problema original

Exemplo: usando a skill em um fluxo de desenvolvimento

Cenário: Você atualizou o código e quer afirmar "Todos os testes passam".

Aplique verification-before-completion:

1. IDENTIFY o comando: por exemplo, pytest.
2. RUN depois das suas mudanças:

   pytest
   

3. READ a saída e verifique o código de saída 0.
4. VERIFY:
   • Se os testes falharam, não declare sucesso. Em vez disso, reporte algo como: "Os testes estão falhando: 3 testes falhando em test_user_flow.py. Ver saída do pytest."
   • Se os testes passaram, você pode afirmar: "Todos os testes passam (pytest, exit code 0)."
5. ONLY THEN marque a tarefa como concluída, envie os commits ou abra um pull request.

Você pode aplicar esse padrão a qualquer afirmação de status: builds, linters, formatação ou correções de bugs.

Integração com agentes e automação

Se você usa agentes ou scripts que ajudam no desenvolvimento:

• Configure-os para que qualquer afirmação sobre testes, builds ou correções seja precedida pela execução de um comando concreto, acompanhada de um resumo da saída.
• Exija que o agente referencie o comando executado e o resultado, por exemplo:
  • "Ran npm test: exit code 0, 0 failing tests."
  • "Ran npm run build: exit code 1, build failed. Not claiming completion."

Em revisões ou pipelines de CI, você pode tratar qualquer afirmação sem evidência como incompleta de acordo com verification-before-completion.

Adaptando à sua stack e ao seu ambiente

O repositório não impõe uma linguagem ou framework específicos. Para adaptar a skill:

• Mapeie cada afirmação comum para um único comando inequívoco que a comprove.
• Documente esses mapeamentos no seu repositório (por exemplo em CONTRIBUTING.md ou WORKFLOW.md).
• Incentive ou exija que colaboradores e agentes sempre:
  • Executem esses comandos antes de dizer "feito"
  • Colem ou resumam a saída relevante ao fazer afirmações

Exemplos de mapeamentos afirmação→comando:

• "Backend tests pass" → pytest backend/tests
• "Frontend builds successfully" → npm run build em frontend/
• "Go module is clean" → go test ./... e golangci-lint run

FAQ

Qual é a regra principal da verification-before-completion?

A regra principal é a "Lei de Ferro":

NO COMPLETION CLAIMS WITHOUT FRESH VERIFICATION EVIDENCE

Se você não acabou de executar o comando de verificação relevante e inspecionar sua saída, não pode, honestamente, declarar sucesso.

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

Evidência de verificação é a saída recente de um comando que testa diretamente a sua afirmação, como:

• Uma execução de suíte de testes com 0 falhas e exit code 0
• Uma execução de linter que não reporta erros e termina com status de saída bem-sucedido
• Um comando de build que conclui com sucesso (exit 0)
• Um script de reprodução ou teste para um bug que agora passa

Resultados antigos, suposições ou "deve funcionar" não contam como evidência sob essa skill.

Posso me apoiar em execuções anteriores de testes se nada mudou?

Dentro de verification-before-completion, a resposta padrão é não. A skill enfatiza verificação recente antes de cada nova afirmação de conclusão. Se você quiser se apoiar em execuções anteriores, deve ser explícito e cuidadoso sobre em quais condições isso é aceitável, reconhecendo que isso enfraquece a garantia.

Essa skill exige ferramentas ou linguagens específicas?

Não. A skill verification-before-completion é independente de ferramenta. Ela funciona com qualquer stack em que você possa:

• Definir comandos que verifiquem o comportamento (testes, linters, builds, scripts)
• Rodá-los sob demanda
• Interpretar seus códigos de saída e saídas

Você apenas preenche com os comandos relevantes ao seu projeto e segue as etapas da Gate Function.

Em que isso é diferente de apenas "rodar testes" de vez em quando?

A diferença está na disciplina e consistência:

• Você executa o comando de verificação sempre antes de declarar conclusão.
• Você sempre lê a saída em vez de presumir sucesso.
• Você trata qualquer afirmação sem evidência como inválida.

Isso transforma rodadas de testes e builds em um gate formal, não em algo opcional.

A verification-before-completion serve para testes manuais?

Sim, desde que você consiga definir um procedimento claro que atue como um "comando" para a afirmação. Por exemplo:

• Documentar um teste manual passo a passo que reproduz um bug
• Executá-lo após sua mudança
• Registrar o resultado como evidência

No entanto, a skill funciona melhor quando a verificação é automatizada via scripts ou frameworks de teste, para que os resultados sejam repetíveis e fáceis de reexecutar.

Onde posso ver a definição original da skill?

A descrição oficial da skill verification-before-completion está no arquivo SKILL.md no repositório obrа/superpowers:

• Repositório: https://github.com/obra/superpowers
• Arquivo da skill: skills/verification-before-completion/SKILL.md

Consulte esse arquivo para o texto exato do princípio, da Lei de Ferro, da Gate Function e de exemplos de falhas comuns a evitar.