keep-the-caveat-with-the-number
Um número e sua ressalva têm de ser um único artefato. Dois parágrafos se afastam; um componente não tem como.
Conferida por quem revisou e leu o cartão, não reivindicada pelo próprio arquivo. Um cartão que o agente destila durante uma execução que consumiu conteúdo não confiável nasce contaminado e fica retido para revisão antes de alguma vez ser recuperado.
Quando ele vem à mente
- publicando o resultado de um benchmark
- colocando uma métrica numa página
- o número precisa de contexto
- resumindo uma medição
Evite e Verifique são onde costuma estar o valor. Faça é a seção que todo mundo escreve.
O corpo do cartão acima é uma tradução. O original em inglês é o que a CLI importa, o que o agente lê em execução e o que o hash abaixo atesta.
Gatilho
Você está colocando um número medido em algum lugar que um leitor vai ver: um README, uma landing page, notas de release, um dashboard, um relatório. O número é verdadeiro e precisa de uma frase ao lado para não enganar — a amostra era pequena, o recorte era fácil, o efeito não foi significativo, o benchmark era nosso.
Não se aplica a um número cujo significado é completo por si só. "O build levou 41 segundos" não precisa de nada.
Faça
- Escreva a ressalva primeiro, antes do número. Se você não consegue declarar a limitação em uma frase, ainda não entende a medição bem o suficiente para publicá-la.
- Faça a ressalva estruturalmente anexada. Coloque-a no mesmo componente, na mesma linha de tabela, no mesmo retorno de função — algo que não consiga renderizar o número sem ela.
- Coloque-a acima do número, ou ao lado. Nunca abaixo.
- Faça o próprio número ser derivado: leia-o a partir do artefato que a medição produziu, para que ele se mova quando a medição se mover.
Evite
O número na manchete e a ressalva numa nota de rodapé, num asterisco, numa seção recolhida, ou no parágrafo seguinte. Todos esses são o mesmo bug com estilizações diferentes: o leitor forma a crença primeiro, e uma correção que chega depois precisa superar uma crença que já existe.
Evite também a versão de segunda ordem — um componente que consegue renderizar o número com a ressalva omitida. Se a qualificação é um argumento opcional, ela será omitida, e será omitida por alguém enxugando um parágrafo que nunca teve a intenção de mudar o significado.
E não parafraseie uma ressalva que foi escrita com cuidado. É na reescrita que "não significativo por si só" vira "perto de ser significativo".
Verifique
Tente escrever o número sem a ressalva e observe isso falhar. Apague o argumento de qualificação, ou coloque um número nu numa página, e rode o build.
Se compilar, o pareamento é uma convenção em vez de um mecanismo, e convenções sobrevivem exatamente enquanto ninguém estiver com pressa.
Risco
Aplicado em excesso, isso torna relatórios comuns pesados: nem todo número é um benchmark, e uma ressalva num número que não precisa de uma treina as pessoas a pular ressalvas.
O risco mais difícil é que um mecanismo parece ser a resposta inteira. Um componente que sempre renderiza alguma ressalva não checa se a ressalva é a certa. A frase ainda precisa ser escrita honestamente por uma pessoa; isso só impede que ela seja descartada depois.
Como usar
O cartão é dado. Clone o repositório e importe pelo caminho — o que chega pela rede é tratado como contaminado e fica retido para aprovação, que é o comportamento desejável e a razão de não haver um instalador de uma linha aqui.
git clone https://github.com/brcampidelli/chimera-agent.gitchimera skills-import chimera-agent/skills/keep-the-caveat-with-the-number/SKILL.mdIntegridade
SHA-256 do arquivo como publicado. Quem importa pode conferir que o que recebeu é o que esta página mostrou.
98a524b60de3f913785f477d03a8a49b428afe7f31d9996b72563f17f8b287d6