Proof-It-Works

Fornece um portão rígido para determinar se o trabalho está realmente concluído, exigindo evidências reproduzíveis de que uma alteração funciona, antes de ser considerada finalizada.

O que é Proof-It-Works?

A habilidade Proof-It-Works é um portão de qualidade rigoroso para agentes de IA (como Claude Code, Cursor, Codex) que determina se uma tarefa de desenvolvimento pode ser declarada como 'concluída'. Ela exige mais do que afirmações verbais ou testes unitários isolados: o agente deve produzir artefatos de evidência reproduzíveis, como logs de execução reais, capturas de tela ou resultados de consultas, que um segundo agente ou revisor possa inspecionar de forma independente. A habilidade suporta três perfis de prova — DESIGN (layout, UI, arquitetura), FEATURE (comportamento em tempo de execução) e DATAFLOW (transformação e persistência de dados) — cada um com seu próprio conjunto mínimo de evidências. Ela opera por meio de um processo estruturado: vinculação a um commit de alteração, definição de perfil de prova, coleta de evidências (incluindo sempre um caso reverso que mostra que a alteração falharia antes da alteração), e julgamento final através de um portão rígido que requer que todos os itens obrigatórios estejam presentes e passem. A saída principal é um relatório (`report.md`) que lista as afirmações de aceitação, as evidências coletadas e o veredito final (PASS, FAIL, UNAVAILABLE/BLOCKED, PENDING USER). É particularmente útil para verificar correções de bugs, implementações de recursos, layouts de UI e contratos de API, garantindo que o trabalho não seja aprovado sem prova concreta.

Funciona com~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/fan56/skills/tree/main/public/proof-it-works

Installed? Explore more Programação e Desenvolvimento skills: steipete/bluebubbles, steipete/eightctl, steipete/blucli · View all 6 →

Perguntar na sua IA favorita

Abre um novo chat com esta habilidade de agente já pré-carregada.

Documentação

Proof It Works

Esta habilidade possui uma decisão: se o trabalho pode ser chamado de concluído. É um portão rígido, não um conselho.

1. Lei central: Concluído = Comprovado

  • Uma afirmação não é evidência. Apenas um artefato reproduzível que um segundo agente possa inspecionar conta.
  • Você não pode dizer pronto, corrigido, passando, ou enviado enquanto qualquer item de portão obrigatório na seção 6 estiver faltando.
  • "Deve funcionar", "parece certo", "teoricamente ok" e "compila" não são estados de conclusão.
  • Se a prova for impossível, declare UNAVAILABLE/BLOCKED (seção 7) — nunca PASS. Uma renúncia por escrito do usuário pode fechar um FAIL como FAIL-WAIVED (seção 7). Uma dimensão não testável por máquina pode permanecer PENDING USER e fechar como PASS-BY-USER após aprovação do usuário (seção 7). Essas três — FAIL-WAIVED, PENDING USER, PASS-BY-USER — são as únicas saídas que não são evidência de máquina; nenhuma delas é PASS.
  • A evidência deve vir da árvore de trabalho e do commit de alteração nomeado no relatório (seção 3, Change ref); artefatos desatualizados são inválidos.
  • Esta habilidade controla apenas trabalho com uma superfície de tempo de execução ou um entregável de design. Para esse trabalho, seu conjunto mínimo de evidências (um positivo + um reverso) substitui, não se acumula a, qualquer verificação mais leve. Trabalho sem superfície de tempo de execução está fora do escopo e esta habilidade cede inteiramente. Ela não substitui uma entrega que o usuário já aprovou como mínima.

2. Níveis de evidência

Três níveis em ordem estrita: Claim (verbal ou raciocínio, evidência zero) < Artifact (um arquivo de artefato bruto real da superfície desta tarefa) < Artifact + caso reverso. O portão aceita apenas os dois últimos; qual deles um item precisa é definido pelos itens de portão do perfil selecionado, não por uma regra global. Um Claim nunca suporta PASS, e nenhum item pode ser rotulado acima do que realmente é.

3. Binding / 任务绑定

  • No topo de report.md, cite textualmente a frase da solicitação do usuário que define o alvo de aceitação — uma instrução como "altere X para Y e prove" conta; não precisa afirmar que o trabalho está concluído. Rotule-a como Acceptance target (user verbatim). Somente se a solicitação não definir nenhum alvo de aceitação (nunca diz como o "concluído" deve ser), diga isso em uma linha, peça ao usuário para declarar um e pare — não há nada para controlar. O nível de evidência Claim na seção 2 é um conceito separado e mantém seu nome.
  • Change ref (cabeçalho do relatório) = o commit que contém a alteração sob teste — não o commit que adiciona este relatório, e não necessariamente HEAD. Sem git, use sha256 dos arquivos alterados + lista de arquivos em vez de um hash. Após o relatório ser commitado, HEAD avança; isso é normal, e o verificador julga por Change ref, não por HEAD.
  • Working tree (cabeçalho do relatório) é texto livre, não um enum de dois valores, por exemplo, tracked clean; .proof/ untracked.
  • Declare os arquivos / funções / rotas / componentes que esta alteração tocou, obtidos do diff atual.
  • Cada perfil selecionado deve ter pelo menos um item de evidência que atinja este diff (executa ou inspeciona um caminho tocado). Evidência que não toca nada no diff = FAIL, mesmo que todos os artefatos existam.
  • Uma linha de base DESIGN deve ter uma fonte externa (seção 6, proof-profiles.md); uma linha de base não rastreável é um Claim e falha em seu item de portão.

4. Selecione o(s) perfil(is) de prova

Escolha o perfil cujo teste de uma linha melhor se ajusta à frase de alvo de aceitação do usuário; uma tarefa pode ser DESIGN e FEATURE ao mesmo tempo e deve então satisfazer ambas. Se nenhum perfil corresponder, diga isso em uma linha e pare — não force um perfil em uma alteração sem superfície de tempo de execução.

PerfilTeste de uma linhaDetalhe
DESIGNVocê produziu uma especificação, layout, interação, arquitetura ou contrato que deve ser mostrado implementado, não apenas proposto.references/proof-profiles.md
FEATUREVocê alterou o comportamento em tempo de execução e deve mostrar que funciona e que entrada inválida é rejeitada.references/proof-profiles.md
DATAFLOWUm valor cruza múltiplos estágios (entrada, transformação, persistência, saída) e cada salto deve ser mostrado.references/proof-profiles.md
  • "Meu design foi implementado" -> DESIGN. "Isso funciona" -> FEATURE. "Para onde os dados foram / eles foram persistidos" -> DATAFLOW.

5. Fluxo de execução

Execute em ordem. Não pule ou reordene.

  1. Crie .proof/<task-name>/ no repositório (nome curto em kebab-case). Um artefato não é prova até ser um arquivo aqui.
  2. Escreva 3-7 afirmações de aceitação em report.md ANTES de coletar evidências. Use as 8 colunas id | assertion | expected | pass criterion (checkable) | changed path (file:function/route) | level required | evidence file | depends on. Proíba "parece correto", "parece bem", "funciona como esperado"; use condições verificáveis como "HTTP 200 com body.field X = Y", "largura do retângulo = 120px", "token inválido retorna 401".
    • expected é o resultado previsto preenchido ANTES de qualquer evidência (por exemplo, 401 + BAD_CREDENTIALS, largura do retângulo 240px); FEATURE/DATAFLOW deve preenchê-lo em cada linha, DESIGN pode escrever n/a. Registre o horário de registro no cabeçalho do relatório como Expected registered (UTC): <time> — o pré-registro é autodeclarado; nenhum hash ou ritual em disco.
    • expected e pass criterion são duas expressões de uma condição (previsão vs. verificação decidível). Elas não devem entrar em conflito; uma linha conflitante deve ser corrigida ANTES da coleta. O status é decidido exclusivamente pelo pass criterion contra observed. Se observed atender ao critério, mas desviar de expected, corrija a implementação para alinhar com expected ou marque a afirmação como FAIL — nunca reescreva expected para o valor observado (seção 8).
    • Preencha changed path com o arquivo/função/rota que a afirmação exercita; escreva n/a apenas para linhas DESIGN que não executam nenhum caminho de código. Pelo menos uma afirmação deve executar um caminho de código alterado neste diff e nomeá-lo; uma afirmação em um caminho não tocado não vincula. FEATURE/DATAFLOW deve ter pelo menos uma célula changed path não n/a; DESIGN pode usar n/a.
    • depends on = ids de pré-requisitos separados por vírgula (vazio se nenhum), coletados em ordem topológica. Um pré-requisito conta como satisfeito apenas quando seu status é PASS ou PASS-BY-USER; se for qualquer outra coisa, a linha downstream é NOT RUN (seção 7) e qualquer NOT RUN faz o portão FAIL. O grafo depends on deve ser acíclico — um ciclo é FAIL. Uma linha USER-JUDGMENT é uma folha: nenhuma linha pode listar um id USER-JUDGMENT em depends on.
  3. Dirija a superfície real com comandos realmente disponíveis nesta máquina (por exemplo, npm run dev para iniciar, curl -i -X POST http://localhost:3000/login -d '{"user":"a","pass":"wrong"}' para API, um navegador real + DevTools para UI, tail -f para logs). Salve stdout/stderr/response/screenshot brutos em arquivos numerados (seção 11). raw = a saída completa como capturada, não resumida, extraída ou reordenada; a dessensibilização é uma transformação única aplicada no momento da captura, portanto não quebra "bruto". Substitua tokens / senhas / chaves por *** no arquivo salvo e registre no índice de evidências e ao lado de cada bloco bruto colado redacted: <nome do campo> (N ocorrência(s)) mais o sha256 do arquivo, para que um revisor possa confirmar que nenhuma edição pós-captura ocorreu. Nunca dessensibilize códigos de status, códigos de erro ou qualquer valor do qual uma afirmação dependa. Qualquer placeholder do tipo <启动命令> / <截图工具> deixado no relatório = FAIL; substitua-o pelo comando exato que você executou.
  4. Caso reverso PRIMEIRO. Defina "um comportamento alterado" como cada ramificação adicionada ou modificada no diff (um if/else, guarda, validação ou nova rota); liste cada um no relatório e dê a cada um uma linha na tabela de afirmações. Um caso de limite é decidível: a mesma entrada é aceita (ou se comporta de forma diferente) na implementação anterior à alteração e rejeitada (ou se comporta corretamente) após a alteração. Capture a linha de base anterior à alteração reconstruindo o original — git stash, uma worktree/checkout do commit anterior à alteração ou uma cópia salva do arquivo original — declare qual no relatório, execute o mesmo comando exato nele e salve o resultado como 00-pre-change.log (seção 11). Este "mostrar que falharia antes da alteração" é a linha de base do caso reverso, nunca uma linha de afirmação FAIL terminal (seção 9). Em seguida, para cada comportamento alterado, execute um caso reverso (entrada errada, permissão ausente, valor de limite, pré-condição removida) e registre que ele falha da maneira esperada. Um caso ruim que também falhou antes da alteração não conta. Se o caso for aceito após a alteração, o teste não está no caminho real; corrija e recolete.
  5. Dataflow: antes de coletar, escreva uma linha de transformação esperada em report.md (forma de entrada -> forma de saída) e referencie-a em cada salto. Em seguida, capture uma amostra real por salto — entrada -> intermediário -> persistência -> saída — com o mesmo id de correlação. Para persistência, cole a consulta de leitura real e seu retorno bruto; reimprimir o valor que você escreveu não é um snapshot. Capture também a linha de base anterior à alteração para o caso reverso conforme etapa 4 (00-pre-change.log): ela deve mostrar o valor rejeitado atingindo a saída antes da alteração.
  6. Os valores observados por DESIGN devem vir de fontes capturadas mecanicamente (JSON de estilo computado, getBoundingClientRect, textContent do DOM, saída do CDP) salvas como arquivos; não leia números de uma captura de tela a olho nu. A linha de base deve fornecer uma tolerância numérica (por lado <=2px, por canal <=8); excedê-la = FAIL. Uma captura de tela é apenas revisão por olho humano, nunca a fonte numérica.
  7. Escreva o relatório a partir de references/report-template.md; copie-o, não invente um formato. Mantenha apenas as seções relevantes para o(s) perfil(is) selecionado(s) e exclua as seções inaplicáveis em sua totalidade — excluí-las não viola "copie-o, não invente um formato".
  8. Julgamento do portão (seção 6): PASS apenas se cada item obrigatório existir no nível obrigatório, toda afirmação não USER-JUDGMENT for PASS/PASS-BY-USER, pelo menos uma afirmação carregar um veredito de máquina, e não houver ciclo em depends on; caso contrário FAIL, UNAVAILABLE/BLOCKED, ou PENDING USER (seção 7). Gate e Result usam o mesmo enum e devem ser idênticos.

6. Portão rígido (qualquer item faltando = FAIL)

"Concluído" requer que cada caixa esteja marcada. Um arquivo faltando, caso reverso faltando, mock no caminho real ou evidência fora do diff é FAIL independentemente da narrativa.

  • Completude (sem itens desconhecidos): o relatório afirma o total de afirmações N e lista um status para cada uma das N afirmações. Os únicos status legais são PASS | FAIL | NOT RUN | UNAVAILABLE | BLOCKED | USER-JUDGMENT | PASS-BY-USER. Um status vazio, um status fora deste conjunto ou uma contagem listada que difere de N é FAIL. PASS requer que toda linha não USER-JUDGMENT seja PASS/PASS-BY-USER e nenhum FAIL/NOT RUN/UNAVAILABLE/BLOCKED.
  • USER-JUDGMENT é legal apenas para uma dimensão SEM critério de máquina decidível. Se uma máquina pode julgar a linha, ou a julgou e a condição não se sustenta, seu status é aquele veredito de máquina (PASS/FAIL) — nunca USER-JUDGMENT. Qualquer coisa que uma máquina possa medir deve ser sua própria linha com um veredito de máquina. A afirmação vinculada a este diff (seção 3) nunca pode ser USER-JUDGMENT. Um relatório cuja toda afirmação é USER-JUDGMENT tem uma condição PASS vacuamente verdadeira e é FAIL: pelo menos uma linha deve carregar um veredito de máquina. Testado por máquina e não atendendo ao critério = FAIL, não USER-JUDGMENT.
  • depends on é um DAG: um ciclo é FAIL. Um pré-requisito é satisfeito apenas por PASS ou PASS-BY-USER; nenhuma linha pode depender de uma linha USER-JUDGMENT, então tais linhas são folhas.
  • Global: vinculação se mantém (seção 3), pelo menos uma afirmação vincula ao diff (seção 5 etapa 2); uma linha USER-JUDGMENT nunca conta como PASS e nunca bloqueia o PASS de outro item.
PerfilConjunto mínimo de evidências — todos obrigatórios
DESIGN(a) artefato de linha de base com uma fonte externa: arquivo de design pré-existente + commit de criação, ou a mensagem textual do usuário contendo/aprovando-o, ou uma tabela de especificação incluída como arquivo de linha de base antes de qualquer arquivo de implementação existir, com o bloco de meta fixo (source_type, source_quote_or_path, captured_at_utc, sha256, baseline_method) preenchido no momento da inclusão; engenharia reversa de valores da implementação para a linha de base é proibida; (b) captura de tela de renderização real no commit de alteração; (c) comparação de tamanho, cor, espaçamento, texto, estado para cada elemento no escopo (escopo = todo elemento nomeado no entregável de design; liste elementos excluídos e o motivo), cada linha citando valor da linha de base e um valor observado mecanicamente, com tolerância numérica (<=2px por lado, <=8 por canal) declarada na linha de base; (d) um item reverso com um valor NO limite de tolerância (por exemplo, 243px para uma especificação de 240px em +/-2), mostrado ausente/incompatível via saída bruta; (e) lacunas de especificação declaradas explicitamente: Interpretation (leitura da linha de base escrita antes da implementação, adiciona apenas posição/mapeamento, nunca contradiz um valor de usuário), Excluded (nenhum valor de linha de base existe, escrito textualmente), UNAVAILABLE (valor existe mas não mensurável aqui) — Excluded e UNAVAILABLE em seções separadas do relatório, sem omissão silenciosa; (f) >=1 item de evidência no diff.
FEATURE(a) um transcrição real de I/O dirigida que executa um caminho de código alterado no commit de alteração; (b) um caso reverso por comportamento alterado, sua entrada inválida no limite decidível (aceita/diferente antes da alteração, rejeitada/correta após), apoiada por uma linha de base anterior à alteração 00-pre-change.log e saída bruta mostrando rejeição correta — casos que também falharam antes da alteração não contam; (c) comando/ação exato e change ref registrados; (d) toda afirmação mapeada para um arquivo com um changed path preenchido, e >=1 afirmação executa o caminho alterado e nomeia o arquivo/função/rota alterado; (e) nenhum mock/stub substituindo a cadeia; (f) >=1 item de evidência no diff.
DATAFLOW(0) linha de transformação esperada (forma de entrada -> forma de saída) escrita antes da coleta e referenciada em cada salto; (a) um snapshot por salto (entrada, intermediário, persistência, saída) com o mesmo id de correlação; (b) snapshot de persistência cola a consulta de leitura real + retorno bruto do armazenamento, não uma reimpressão do valor escrito; (c) análise de saída traça de volta todos os valores de forma não ambígua a um valor de entrada no mesmo snapshot, com a linha de transformação esperada listada na seção de análise; (d) linha de base anterior à alteração 00-pre-change.log por caso reverso, mostrando o valor rejeitado atingindo a saída antes da alteração; (e) >=1 item de evidência no diff.

7. Status legais e tratamentos

Status é ponta, não escala. Um portão possui um status; uma linha de afirmação possui um status. NOT RUN, UNAVAILABLE e BLOCKED são estados terminais da linha de afirmação que não podem ser convertidos após o fato. PENDING USER é um estado de espera; a ação do usuário pode movê-lo para PASS-BY-USER ou mantê-lo como FAIL.

  • FAIL: O item de evidência ou condição não foi atendido. O portão falha.
  • NOT RUN: A linha de afirmação não foi executada porque um pré-requisito não foi satisfeito (seção 5). Qualquer NOT RUN no final faz o portão FAIL. Se um pré-requisito falha, suas dependências transitivas são todas NOT RUN; o depends on deve ser verificado na ordem topológica (seção 5, etapa 2) para que este efeito em cascata seja capturado — o grafo completo deve ser verificado a partir das raízes primeiro.
  • UNAVAILABLE: A evidência não pode ser coletada (por exemplo, serviço externo fora do ar, licença expirada, ambiente não provisionado). O portão pode declarar UNAVAILABLE globalmente; uma única linha UNAVAILABLE faz o portão FAIL.
  • BLOCKED: Uma dependência (pessoa, equipe, revisão de segurança, aprovação legal) não está neste momento disponível. Semelhante a UNAVAILABLE, mas geralmente sinaliza um bloqueio humano ou organizacional. Uma única linha BLOCKED faz o portão FAIL.
  • PENDING USER → PASS-BY-USER: Um item de julgamento humano onde um critério de máquina é impossível. O agente marca PENDING USER, aguarda aprovação explícita do usuário, então avança para PASS-BY-USER. Se o usuário recusar, a linha permanece como está e o portão é FAIL. PASS-BY-USER é funcionalmente equivalente a PASS para o propósito de satisfazer pré-requisitos.
  • FAIL-WAIVED é para depuração — veja a seção 9.

8. Violações de integridade de evidência

As violações a seguir quebram a confiabilidade do relatório e resultam em FAIL imediato, mesmo que o portão pareça verde:

  • expected alterado após a coleta (o arquivo raw de evidência não corresponde mais à previsão); verificado comparando o hash sha256 do arquivo raw com o registrado no índice de evidências no momento da coleta.
  • Renderizações de captura de tela com visibilidade hidden, none, opacity: 0, fora da janela de visualização, ou deslocadas; verificado por checkVisibility() do navegador ou equivalente.
  • Saída truncada: a saída raw é maior (em bytes) do que o arquivo raw salvo; verificado por contagem de linhas ou tamanho de arquivo.
  • Evidência pré-alterada coletada após o pós-alteração (selo de tempo do 00-pre-change.log após a coleta pós-alteração); verificado pela ordenação de selo de tempo no índice de evidências.
  • Prompt do usuário ou pergunta de confirmação ignorada: qualquer interação PENDING USER que nunca foi resolvida; verificado por qualquer status PENDING USER não resolvido no final do julgamento.

9. Depuração

O modo de depuração não substitui a prova. É uma fase de solução de problemas que precede a coleta de evidências. Quando ativado:

  • O agente escreve um log de depuração em .proof/<task-name>/debug.md detalhando a linha do tempo de tentativa e erro:
    1. O que você esperava que acontecesse (por exemplo, "Comando curl na URL de desenvolvimento").
    2. O que realmente aconteceu (por exemplo, "Erro de conexão recusada").
    3. O que você tentou a seguir (por exemplo, "Verificou se o servidor de desenvolvimento está em execução").
    4. Resultado (por exemplo, "Servidor iniciado, curl agora funciona").
  • A fase de depuração termina quando o agente pode executar a coleta de prova real. O log de depuração não é evidência.
  • O modo de depuração termina automaticamente quando a primeira coleta de evidência começa.
  • Se a depuração falhar em resolver (depois de 5 tentativas ou a critério do agente), o portão é FAIL-WAIVED. FAIL-WAIVED é um estado de portão terminal que sinaliza que a prova foi tentada mas não pôde ser concluída; um agente ou revisor humano pode aceitar a renúncia em um relatório de depuração. Uma modificação do desenvolvedor ou mudança de ambiente pode transformar um FAIL-WAIVED em um PASS em uma execução posterior. Um FAIL-WAIVED nunca conta como PASS para qualquer propósito.

10. Relatório de encerramento

Depois que o portão passar ou falhar, imprima uma seção de encerramento que inclui:

  • Resultado geral: PASS / FAIL / UNAVAILABLE / BLOCKED / FAIL-WAIVED
  • Resumo das afirmações: número de PASS, FAIL, NOT RUN, UNAVAILABLE, BLOCKED, USER-JUDGMENT, PASS-BY-USER
  • Quaisquer itens bloqueados ou não disponíveis com explicação
  • Data e hora de conclusão do relatório

11. Convenções de nomenclatura de evidências

  • 00-pre-change.log — captura de linha de base para caso reverso
  • 01-positive-case.<ext> — evidência de caso positivo
  • 02-reverse-case.<ext> — captura de caso reverso
  • 03-dataflow-stage-<name>.<ext> — snapshot de estágio de dataflow
  • screenshot-<description>.png — capturas de tela
  • artifact-<description>.json — artefatos de dados como estilos computados

Habilidades Relacionadas