keep-the-caveat-with-the-number
Una cifra y su matiz deben ser un único artefacto. Dos párrafos se separan; un componente no puede.
Conferida por quien revisó y leyó la tarjeta, no reclamada por el propio archivo. Una tarjeta que el agente destila durante una ejecución que consumió contenido no confiable nace contaminada y queda retenida para revisión antes de ser recuperada.
Cuándo viene a la mente
- publicando un resultado de benchmark
- poniendo una métrica en una página
- el número necesita contexto
- resumiendo una medición
Evita y Comprueba es donde suele estar el valor. Haz es la sección que todo el mundo escribe.
El cuerpo de la tarjeta de arriba es una traducción. El original en inglés es lo que importa la CLI, lo que lee el agente en ejecución y lo que atestigua el hash de abajo.
Disparador
Estás colocando una cifra medida en algún lugar donde un lector la verá: un README, una landing page, notas de versión, un panel, un informe. La cifra es verdadera y necesita una frase al lado para no inducir a error — la muestra era pequeña, el segmento era fácil, el efecto no fue significativo, el benchmark era nuestro.
No aplica a una cifra cuyo significado es completo por sí mismo. «El build tardó 41 segundos» no necesita nada.
Haz
- Escribe primero la advertencia, antes que el número. Si no puedes plantear la limitación en una frase, aún no comprendes la medición lo suficiente como para publicarla.
- Haz que la advertencia esté estructuralmente adjunta. Ponla en el mismo componente, la misma fila de tabla, el mismo retorno de función — algo que no pueda renderizar la cifra sin ella.
- Colócala arriba del número, o al lado. No abajo.
- Haz que el número mismo sea derivado: léelo del artefacto que produjo la medición, para que se mueva cuando la medición se mueva.
Evita
El número en el titular y la advertencia en una nota al pie, un asterisco, una sección colapsada, o el párrafo siguiente. Todos esos son el mismo error con distinto estilo: el lector forma la creencia primero, y una corrección que llega después tiene que superar una creencia que ya existe.
Evita también la versión de segundo orden — un componente que puede renderizar la cifra con la advertencia omitida. Si la salvedad es un argumento opcional, se omitirá, y la omitirá alguien que esté ajustando un párrafo sin intención alguna de cambiar el significado.
Y no parafrasees una advertencia que fue escrita con cuidado. Al reformular es donde «no significativo por sí solo» se convierte en «cerca de ser significativo».
Comprueba
Intenta escribir el número sin la advertencia y observa que falla. Elimina el argumento de salvedad, o pon una cifra desnuda en una página, y ejecuta el build.
Si compila, el emparejamiento es una convención en lugar de un mecanismo, y las convenciones sobreviven exactamente mientras nadie tenga prisa.
Riesgo
Aplicado en exceso, esto vuelve pesado el reporte ordinario: no todo número es un benchmark, y una advertencia en una cifra que no la necesita entrena a la gente a saltarse las advertencias.
El riesgo más difícil es que un mecanismo se sienta como la respuesta completa. Un componente que siempre renderiza alguna advertencia no verifica si la advertencia es la correcta. La frase todavía tiene que ser escrita honestamente por una persona; esto solo evita que sea eliminada después.
Cómo usarla
La tarjeta es un dato. Clona el repositorio e impórtala por ruta: lo que llega por la red se trata como contaminado y queda retenido a la espera de aprobación, que es el comportamiento deseable y la razón por la que aquí no hay un instalador de una línea.
git clone https://github.com/brcampidelli/chimera-agent.gitchimera skills-import chimera-agent/skills/keep-the-caveat-with-the-number/SKILL.mdIntegridad
SHA-256 del archivo tal como se publicó. Quien lo importe puede comprobar que lo que recibió es lo que mostró esta página.
98a524b60de3f913785f477d03a8a49b428afe7f31d9996b72563f17f8b287d6