Contrato de Evidência

O que Contrato de Evidência faz?

Crie planos que sejam testáveis e baseados no repositório real, em vez de suposições plausíveis.

Ativação

Aplique esta habilidade automaticamente quando a tarefa exigir um plano de implementação não trivial ou revisão de plano. Não espere o usuário invocá-la explicitamente.

Ignore o contrato completo para mudanças triviais onde o alvo, comportamento e verificação já são óbvios. Em vez disso, indique a verificação simples.

Esta habilidade é exclusiva para planejamento. Não edite arquivos de implementação a menos que o usuário também tenha solicitado a execução do plano.

Fluxo de Trabalho

1. Estabelecer intenção e sucesso

Reafirme o resultado desejado em uma frase. Extraia comportamento de aceitação concreto da solicitação. Se a redação for ambígua, investigue o repositório antes de perguntar ao usuário. Pergunte apenas quando resultados materialmente diferentes permanecerem possíveis após a investigação.

2. Coletar evidências mínimas suficientes

Antes de propor arquitetura ou nomear arquivos afetados:

1. Leia PROJECT_CONTEXT.md quando presente.
2. Localize os pontos de entrada da funcionalidade com busca direcionada.
3. Leia o menor conjunto de arquivos de implementação, configuração e teste relevantes.
4. Rastreie chamadores importantes, dependências, limites de persistência e interfaces públicas.
5. Registre contradições entre documentação e código. Trate código e comportamento executável como evidência mais forte.

Evite varreduras amplas do repositório quando evidências direcionadas forem suficientes.

3. Classificar toda alegação material

Use estes rótulos internamente e exponha-os quando útil:

• Observado: diretamente suportado por um arquivo, símbolo, resultado de comando, teste ou observação de tempo de execução.
• Inferido: fortemente implícito por evidências observadas, mas não demonstrado diretamente.
• Desconhecido: informação material que não foi estabelecida.

Nunca apresente uma alegação inferida ou desconhecida como fato. Inclua uma localização de código ou observação de ferramenta para alegações observadas importantes. Não invente caminhos de arquivo, APIs, dependências ou comportamento existente.

4. Resolver desconhecidos bloqueadores

Investigue desconhecidos que possam alterar arquitetura, escopo, fluxo de dados, compatibilidade ou comportamento de aceitação. Se um desconhecido não puder ser resolvido localmente:

• declare-o explicitamente,
• explique por que é importante,
• proponha a suposição delimitada mais segura, e
• pergunte ao usuário apenas se prosseguir puder produzir o resultado errado.

5. Produzir um plano protegido por evidência

Cada item de plano não trivial deve incluir:

1. Mudança: o menor passo de implementação coerente.
2. Evidência: fatos observados do repositório que justificam o passo, com caminhos ou símbolos relevantes.
3. Superfície afetada: arquivos, interfaces, dados, chamadores, dependências ou fluxos de trabalho propensos a mudança.
4. Verificação: uma observação executável de teste, compilação, lint, execução ou aceitação.
5. Risco ou suposição: apenas quando material, rotulado como inferido ou desconhecido.

Prefira planos que mapeiem um requisito para uma verificação observável. Inclua cobertura de regressão para correções de bugs e mudanças sensíveis a compatibilidade.

6. Executar o portão de planejamento

Antes de apresentar o plano, verifique:

• Cada resultado solicitado mapeia para pelo menos um item do plano.
• Cada item do plano tem evidência e uma verificação de sucesso concreta.
• Arquivos e símbolos nomeados foram observados, não adivinhados.
• Suposições materiais estão visíveis e classificadas.
• Dependências e limites de integração estão cobertos.
• O plano usa a menor mudança que satisfaz a solicitação.
• Nenhuma funcionalidade especulativa ou refatoração não relacionada foi adicionada.

Se o portão falhar, investigue ou revise o plano antes de retorná-lo.

Formato de saída

Mantenha o resultado conciso, a menos que a tarefa seja complexa.

## Contrato de evidência
- Observado: `caminho/para/arquivo` estabelece ...
- Inferido: ... porque ...
- Desconhecido: ...; suposição delimitada ou decisão necessária ...

## Plano
1. **Mudança** ...
   - Evidência: ...
   - Afetado: ...
   - Verificar: ...
   - Risco/Suposição: ...

## Portão de conclusão
- [ ] Mapeamento requisito-para-verificação está completo
- [ ] Nenhuma suposição não rotulada permanece
- [ ] Verificações de aceitação são executáveis

Omita seções inferidas ou desconhecidas vazias. Para planos pequenos, comprima cada item em uma única linha, mantendo evidência e verificação.

Antipadrões

Não:

• produza um plano apenas a partir de nomes de arquivos,
• use "provavelmente" ou "deveria" sem marcar uma inferência,
• afirme que testes passam sem executá-los,
• substitua uma verificação simulada por um caminho de aceitação real disponível,
• sobrecarregue o usuário com perguntas respondíveis a partir do repositório,
• transforme o contrato em burocracia para mudanças triviais,
• comece a implementação meramente porque o plano está completo.