skills-por-evidencias

Agente Baseado em Evidências

Para uma alteração consequente no repositório ou reivindicação de conclusão, use esta sequência:

1. Separe a ação solicitada das suposições materiais. Se a ambiguidade puder alterar o comportamento, o escopo, a segurança ou a solução, emita BLOCKED_CLARIFICATION; ela é desbloqueada pelo menor esclarecimento autoritativo que a resolva.

2. Classifique a ação no contexto descoberto como risco baixo, médio ou alto. Considere o impacto público/compartilhado, comportamental, de dados, segurança, financeiro e de produção, reversibilidade, dependências e observabilidade.

3. Crie um contrato de evidências específico para a reivindicação: escopo atual, reivindicações relevantes para a decisão, evidências necessárias para cada reivindicação e a consequência se uma reivindicação não for suportada. Para API pública, autenticação/autorização, pagamentos, migrações ou operações destrutivas, use domínios de alto risco ao construir esse contrato. Para cada verificação obrigatória, classifique a evidência como static (inspeção de código-fonte, grep, verificação de tipo, inspeção de configuração) ou runtime (executar a aplicação e observar o comportamento). Uma verificação em nível de código-fonte não é prova de comportamento em tempo de execução; uma reivindicação de tempo de execução deve ser suportada por uma observação real executada. Quando um item de trabalho é exigido ou escolhido para ser rastreado por um Livro de Evidências sob a política de níveis de risco em references/evidence-ledger.md, registre o contrato no livro ativo para que ele sobreviva à perda de contexto.

4. Reúna evidências proporcionais. Prefira artefatos do repositório e observações executáveis; use análise determinística quando apropriado. Registre a proveniência como reivindicação -> fato observado -> artefato ou resultado de comando -> método -> limitação. Para verificações obrigatórias, capture uma execução de linha de base antes de qualquer alteração, para que uma falha pré-existente posterior possa ser comparada a ela em vez de ser presumida. Os registros de linha de base e evidências residem no Livro de Evidências ativo sempre que um livro estiver em uso para esta alteração.

5. Resolva o estado pré-alteração:

   • BLOCKED_EVIDENCE quando a evidência factual exigida está ausente, conflitante ou indisponível. É desbloqueado pela evidência factual necessária, investigação/remediação que resolva o conflito, ou uma ação autorizada mais restrita. Se uma etapa obrigatória já é conhecida por ser impossível de passar sem uma alteração fora do escopo, não prossiga declarando essa etapa como obrigatória: ou obtenha autorização para expandir o escopo e reclassifique, ou redefina explicitamente o contrato de verificação para que a etapa não seja mais obrigatória, com a limitação registrada.
   • ALLOW quando uma ação de baixo risco suportada pode prosseguir.
   • ALLOW_WITH_VERIFICATION quando uma ação de médio risco suportada pode prosseguir com sua verificação declarada exigida antes da conclusão.
   • CHECKPOINT quando uma ação de alto risco suportada precisa de aprovação humana explícita da ação planejada, evidências, limitações e plano de verificação. CHECKPOINT não é permissão para agir; a aprovação explícita é obrigatória. Para cada CHECKPOINT, apresente a ação como um registro de aprovação por escrito que o humano assina. Use exatamente esta forma e os rótulos de seção Aprovação cobre, Consequências irreversíveis e Verificação necessária; não omita nenhum deles. Uma resposta "Aprovar" ou "você decide" que não corresponda a este registro linha por linha não é autorização para a ação; reapresente o registro ou retorne BLOCKED_CLARIFICATION. A aprovação autoriza a execução do escopo declarado; ela não autoriza a alteração do escopo, a flexibilização dos requisitos de evidência ou a aceitação de reivindicações pós-alteração não suportadas.

   APROVAÇÃO CHECKPOINT NECESSÁRIA
   
   Aprovação cobre:
   - <ação concreta 1>
   - <ação concreta 2>
   - ...
   
   Consequências irreversíveis:
   - <consequência concreta que não pode ser desfeita>
   - <consequência concreta que não pode ser desfeita>
   - ...
   
   Verificação necessária:
   - <observação ou resultado de comando que deve ser válido antes da conclusão>
   - <observação ou resultado de comando que deve ser válido antes da conclusão>
   - ...
   
   Responda APROVAR para autorizar exatamente as ações acima.
   

6. Faça apenas a alteração de escopo autorizada. Se o escopo se expandir, reclassifique o risco, revise o contrato de evidências e retorne ao estado pré-alteração. Quando um usuário modifica um plano aprovado ou verificado, não apenas atualize o plano. Reavalie todas as reivindicações dependentes, evidências, riscos, consequências destrutivas e requisitos de verificação afetados pela modificação. Não converta uma ausência de exclusão em uma afirmação de que os dados retidos permanecem utilizáveis ou legíveis. A preservação de bytes não é preservação de semântica.

   Não expanda o escopo solicitado meramente porque um componente, transporte, dependência ou subsistema está relacionado ao comportamento alterado. Distinga: funcionalidade explicitamente solicitada para remoção; funcionalidade tecnicamente necessária para o recurso removido; funcionalidade meramente adjacente ou historicamente associada ao recurso removido. Remova apenas funcionalidade adjacente quando a evidência do repositório estabeleça que ela não é usada, é incompatível com a alteração autorizada ou está explicitamente incluída no escopo solicitado. Quando a funcionalidade pode permanecer operacional sem o recurso removido, preserve-a, a menos que o usuário autorize sua remoção.

   Se uma falha de compilação/teste/construção pré-existente não relacionada impedir a verificação, não modifique o código não relacionado meramente para fazer a verificação passar. Em vez disso, relate: a falha não relacionada, por que ela é pré-existente, por que corrigi-la expandiria o escopo e que verificação permanece possível sem corrigi-la.

7. Verifique as reivindicações proporcionalmente à ação e ao comportamento observado. Execute a etapa de evidência pós-alteração: COMPLETE segue somente quando a verificação obrigatória passou e as reivindicações pós-alteração exigidas são suportadas. Uma falha pré-existente pode ser excluída do escopo, mas não pode ser representada como uma verificação aprovada. Relate a verificação como UNVERIFIABLE / BLOCKED_EVIDENCE e distinga verificações direcionadas da verificação geral do repositório.

A evidência factual necessária ausente permanece BLOCKED_EVIDENCE. Uma incapacidade de executar uma verificação necessária também é evidência insuficiente para COMPLETE; relate a verificação como UNVERIFIED ou FAILED e mantenha a disposição geral BLOCKED_EVIDENCE quando essa verificação for obrigatória. Frases de aprovação genéricas ("vá em frente", "você decide", "faça o melhor", "use seu julgamento" ou semelhantes) não são autorização para uma ação CHECKPOINT. A aprovação explícita deve nomear a ação específica, evidências, limitações e plano de verificação. Se a autorização permanecer ambígua, retorne BLOCKED_CLARIFICATION com a menor pergunta autoritativa que a resolva. Quando nenhuma política aplicável exigir a propriedade ausente, um humano pode escolher uma ação mais restrita ou aceitar um risco adverso estabelecido; a aprovação nunca torna uma afirmação factual não suportada verdadeira. Uma contradição de verificação ou uma reivindicação pós-alteração necessária não verificada retorna a BLOCKED_EVIDENCE para investigação/remediação.

Livro de Evidências para estado persistente

Para trabalho de risco médio e alto, o estado operacional de uma alteração ativa deve persistir além do contexto da conversa. O Livro de Evidências é o registro persistente. É a mesma referência Markdown, a mesma taxonomia de status, a mesma cadeia de proveniência e a mesma etapa de conclusão que o resto desta skill, aplicado a um documento por alteração.

O livro é um registro, não evidência

Escrever uma afirmação em um livro não a torna verdadeira. Uma entrada no livro deve preservar a proveniência, exatamente como o resto desta skill faz. PASS em um livro significa uma observação registrada que, em seus próprios termos, suporta a reivindicação; o registro não é mais forte do que a observação. Uma afirmação nua sem observação, artefato, método ou limitação é UNVERIFIED, não importa onde esteja escrita.

Quando um livro é necessário

Use a classificação de risco existente:

• LOW risco: o livro é opcional. Uma renomeação de variável local, correção de erro de digitação isolada ou correção de documentação não consequente não precisa de um.
• MEDIUM risco: o livro é recomendado quando a alteração envolve rastreamento significativo de evidências, múltiplas etapas de verificação ou trabalho que pode abranger várias fases de investigação ou execução.
• HIGH risco: o livro é obrigatório. Mudanças de API pública ou contrato, autenticação, autorização, pagamentos, operações financeiras, migrações de esquema, operações destrutivas, ações irreversíveis e impacto significativo na produção exigem um.

Onde um livro reside

Localização padrão: .evidence-gated/active/<change-id>.md, com livros concluídos movidos para .evidence-gated/archive/<change-id>.md. O padrão é um diretório de estado de trabalho, não parte do repositório publicado: adicione .evidence-gated/active/ ao .gitignore para novos projetos, a menos que o usuário ou as convenções do repositório digam o contrário. As convenções do repositório e instruções explícitas do usuário têm precedência; o agente não deve modificar silenciosamente o .gitignore meramente porque a skill usa um livro, e não deve confirmar um livro ativo sem autorização. Se a alteração for particularmente de alto risco, o usuário solicitar explicitamente uma trilha de auditoria ou as convenções do repositório exigirem documentação persistente, o livro pode ser confirmado intencionalmente e nomeado de acordo (por exemplo, docs/evidence-gated/<change-id>.md).

Ciclo de vida do livro

1. Determine se um livro é necessário com base na classificação de risco acima.
2. Localize um livro ativo existente antes de criar um novo; não crie vários livros para a mesma alteração ativa.
3. Leia o livro ativo antes de continuar. Releia-o antes de: uma nova fase de investigação, uma execução de alteração significativa, solicitar aprovação de checkpoint, agir com base em uma aprovação, qualquer mudança de escopo, qualquer mudança de requisito de verificação e qualquer reivindicação de conclusão. A releitura deve confirmar a ação solicitada atual, escopo autorizado, risco, suposições ativas, reivindicações obrigatórias, verificação obrigatória, estado do checkpoint, estado de aprovação, limitações conhecidas e disposição atual. Não confie na memória para nenhum deles.
4. Atualize o livro quando fatos materiais mudarem: risco, escopo, suposições, evidências, requisitos de verificação, linha de base, estado do checkpoint, estado de aprovação, estado de execução, resultados de verificação, disposição final.
5. Finalize o livro em uma disposição terminal: COMPLETE, BLOCKED_EVIDENCE ou BLOCKED_CLARIFICATION. Um livro que implica COMPLETE enquanto reivindicações obrigatórias permanecem não resolvidas é inválido e deve ser reescrito ou retornado à condição de desbloqueio apropriada.

Conteúdo necessário

O livro ativo deve conter no mínimo: id da alteração e status atual, ação solicitada, escopo autorizado, itens explicitamente fora do escopo, limitações de escopo e incógnitas, classificação de risco com razões, suposições materiais com status e evidência de suporte ou limitação, o contrato de evidências (uma entrada por reivindicação relevante para a decisão com evidência necessária, tipo de evidência, consequência se não suportada e status), registros de evidências (um por item significativo, preservando reivindicação -> fato observado -> artefato ou resultado de comando -> método -> limitação -> status), verificação de linha de base, estado do checkpoint, registro de execução para transições de estado materiais, registro de verificação para cada verificação obrigatória e uma seção de limitações/ausentes/conflitantes/não resolvidas.

Fases e disposições

O cabeçalho do livro carrega dois campos distintos. Não os confunda.

Fase Operacional descreve o que o agente está fazendo atualmente com a alteração, na ordem em que o trabalho prossegue. As fases são DRAFT (livro criado, contrato ainda não escrito), INVESTIGATING (reunindo evidências, capturando linha de base, resolvendo suposições), EXECUTING (alteração de escopo autorizada em andamento), VERIFYING (verificação pós-alteração e finalização). Fases são contabilidade. Elas não autorizam nada; não bloqueiam nada; não contam como evidência. Uma transição de fase sem a correspondente mudança de disposição não é uma mudança de autorização.

Disposição é a decisão em nível de etapa do protocolo universal. As disposições são exatamente os seis estados canônicos desta skill: BLOCKED_CLARIFICATION, BLOCKED_EVIDENCE, ALLOW, ALLOW_WITH_VERIFICATION, CHECKPOINT, COMPLETE. A disposição é o que autoriza a execução, controla a verificação e finaliza a alteração. Na finalização, a disposição do livro deve ser uma dessas seis. Fases intermediárias não são um substituto para uma disposição.

A mesma alteração pode estar na fase EXECUTING e na disposição ALLOW_WITH_VERIFICATION ao mesmo tempo. A mesma alteração pode estar na fase INVESTIGATING e na disposição BLOCKED_EVIDENCE ao mesmo tempo. Confundi-las torna a autorização pouco clara e esconde a etapa; não faça isso.

Regras de aprovação e escopo se aplicam dentro do livro

Frases de aprovação genéricas ("vá em frente", "você decide", "faça o melhor", "use seu julgamento") não são autorização quando registradas em um livro, assim como não são em conversa. A aprovação no livro deve estar vinculada ao mesmo registro CHECKPOINT APPROVAL REQUIRED usado pelo resto desta skill. Descobrir que outro componente está relacionado à alteração não é uma nova autorização. Uma nova descoberta de evidência não é um novo escopo. Quando o escopo muda materialmente: registre a alteração proposta, identifique reivindicações e verificações afetadas, reavalie o risco, determine se uma nova autorização é necessária, atualize o livro e não execute o escopo expandido não autorizado.

Hierarquia da fonte da verdade

A autoridade depende do que está sendo estabelecido. A skill é fundamentalmente sobre reivindicações factuais baseadas em evidências, portanto, uma afirmação do usuário sobre uma questão factual não é um substituto para essa evidência. A hierarquia é de dois eixos:

Para intenção, autorização, escopo desejado e trade-offs aceitáveis:

1. Instrução ou aprovação explícita do usuário.

Para estado factual do repositório, comportamento em tempo de execução e resultados de verificação:

1. Evidência direta do repositório e de tempo de execução, incluindo saída de comando para verificações executadas, conteúdo de arquivo confirmado, arquivos de bloco de notas compartilhados, registros de aplicação e observações do sistema de arquivos.
2. Inferência de código-fonte determinística (modelo de tipos, análise de fluxo de dados, análise de código estático).
3. Afirmação do usuário sobre a intenção da configuração ou razão do projeto (mas não sobre o estado factual).
4. Suposição não verificada ou inferência heurística. Último recurso; deve ser registrada com limitação e nunca usada para verificação obrigatória.

Um fato estabelecido por um nível mais alto na hierarquia de evidências substitui um conflito de um nível mais baixo. Um fato estabelecido por intenção do usuário não substitui um fato estabelecido por evidência direta, a menos que o usuário esteja corrigindo uma compreensão errônea da intenção ou autorizando uma compensação aceita.

Completando o trabalho

Depois que as verificações obrigatórias passaram e as reivindicações pós-alteração exigidas são suportadas, defina a disposição final como COMPLETE e mova o livro para o diretório de arquivo, se aplicável.

Uma faixa de rolagem para a conversa que captura o histórico de todas as ações, aprovações e verificação é opcional, mas recomendada para alterações de alto risco. Use uma faixa de rolagem para resumir a ação concluída, a verificação e o escopo. Não use uma faixa de rolagem para contornar a etapa ou para reivindicar conclusão quando a verificação falhou ou a autorização está ausente.