Documentação baseada em evidências
Uma afirmação é documentação apenas quando carrega os meios para verificá-la. Este skill é o padrão e o mapa: dez cânones, e onde cada um é definido, aplicado e propagado.
Ele é um navegador, não uma segunda cópia. Cada lei abaixo tem exatamente um lar — esse é o
cânon 3, e um navegador que reafirmasse a doutrina quebraria a regra que está indexando.
A declaração completa de cada cânon, sua justificativa e sua aplicação estão em
documentation.md → Os cânones.
Os dez cânones
- Uma afirmação carrega seu endereço —
arquivo:linha, um comando com sua saída, um nome de teste; uma lição nomeia seu commit. - Números são calculados, nunca reafirmados.
- Cada fato tem exatamente um lar — outros linkam, nunca reafirmam.
- Uma referência resolve a partir de onde o documento é lido — não de onde ele vive.
- Verde que ninguém viu ficar vermelho não é evidência.
- Uma verificação prova seu escopo e nada além dele.
- Silêncio não é aprovação — pergunte o que um mecanismo imprime quando não olhou.
- Uma estimativa nunca é anunciada como uma medição — uma regra declara sua condição de evidência.
- O que não foi verificado é impresso ao lado do que foi.
- O documento viaja na mudança que o tornou verdadeiro — e uma correção é anexada, nunca sobrescrita.
Eles são epistêmicos: o que torna uma afirmação documentação. A camada operacional — o que
fazer em um dado gatilho, com uma verificação e um critério de saída — está em
learned.md. Quando os dois parecem dizer a mesma
coisa, o cânon é o porquê e a regra é o como.
Para onde ir
| Você está prestes a… | Leia | Porque |
|---|---|---|
| configurar a documentação de um projeto do zero | documentation.md → O inventário | quatro perguntas respondidas antes da primeira linha de trabalho |
| registrar uma decisão para que ela sobreviva ao seu autor | Registros e ids + templates/decisions.md | ids anexados, marcadores de borda, um lar para a decisão |
| alterar algo e não órfão a documentação | O Loop da Documentação + A matriz de propagação | quais documentos uma mudança deve, começando pela linha meta |
| decidir onde um fato pertence | Fonte única de verdade | dois lares discordam no dia em que um deles é atualizado |
| construir uma verificação que não pode mentir | gates.md | três eixos, a escada de aplicação, armamento progressivo, sondagem |
| confiar em um mecanismo que relata sucesso | gates.md → Falso sucesso | a falha que remove o motivo para olhar |
| conectar uma verificação às ferramentas do próprio agente | hooks.md | o contrato do gancho, e por que um guardião travado permite a ação |
| auditar a documentação que um projeto já possui | setup.md | sete passagens, mais baratas primeiro, a saída é um plano de correção |
| levar uma lição para a próxima execução | retrospective.md | carimbe primeiro (o gatilho frio a lê), depois pode para um limite de dez; toda lição nomeia seu commit |
| semear um portão em um projeto hospedeiro | templates/docgate.sh | ele semeia verde: dormente onde ainda não há entrada |
| afirmar que um agente se comporta | tdd.md → Quando a coisa sob teste é um agente — nomeado em vez de linkado, porque os links fora de diretório deste navegador quebram sempre que um empacotador envia este skill sozinho | o endereço é um id de rastreio e a asserção que executou (cânon 1); um juiz que ninguém viu discordar é um verde que ninguém viu ficar vermelho (cânon 5) |
| levar uma mudança inteira até a aceitação | task-pipeline | este skill é o padrão; aquele é como uma mudança chega ao repositório |
Quando isso se aplica
O limite é "será lido como verdadeiro." Um registro de decisão, um README, um relatório de aceitação, um runbook, um changelog para usuários, uma descoberta de auditoria, uma afirmação de que algo foi verificado.
Não através deste skill: um rascunho, pensar em voz alta, uma resposta em chat, uma
mensagem de commit, um comentário de código. Exigir um arquivo:linha para "deixe-me
verificar isso" é a maneira mais rápida de ensinar um agente a contornar a regra onde ela
realmente protege algo.
Frase de recusa — "без доков" / "na minha palavra". Funciona em uma tarefa que de outra forma passaria por aqui: faça diretamente e diga em voz alta que a afirmação não tem respaldo, em vez de apresentar uma estimativa como uma medição (cânon 8).
O único teste
Antes de um documento ser enviado, leia-o para encontrar a frase que te envergonharia se alguém perguntasse "como você sabe?" — e ou dê a essa frase seu endereço, ou a apague. Tudo acima é essa pergunta, tornada mecânica.