keep-the-caveat-with-the-number
A figure and its qualification must be one artifact. Two paragraphs drift apart; one component cannot.
Conferred by a reviewer who read the card, not claimed by the file about itself. A card the agent distils during a run that consumed untrusted content is born tainted and is held for review before it is ever retrieved.
When it comes to mind
- publishing a benchmark result
- writing a metric into a page
- the number needs context
- summarising a measurement
Avoid and Check are where the value usually is. Do is the section everybody writes.
Trigger
You are putting a measured figure somewhere a reader will see it: a README, a landing page, release notes, a dashboard, a report. The figure is true and it needs a sentence beside it to not mislead — the sample was small, the slice was easy, the effect was not significant, the benchmark was ours.
It does not apply to a figure whose meaning is complete on its own. "Build took 41 seconds" needs nothing.
Do
- Write the caveat first, before the number. If you cannot state the limitation in one sentence, you do not yet understand the measurement well enough to publish it.
- Make the caveat structurally attached. Put it in the same component, the same table row, the same function return — something that cannot render the figure without it.
- Put it above the number, or beside it. Not below.
- Make the number itself derived: read it from the artifact the measurement produced, so it moves when the measurement moves.
Avoid
The number in the headline and the caveat in a footnote, an asterisk, a collapsed section, or the paragraph after. Those are all the same bug with different styling: the reader forms the belief first, and a correction arriving afterwards has to overcome a belief that already exists.
Avoid also the second-order version — a component that can render the figure with the caveat omitted. If the qualification is an optional argument, it will be omitted, and it will be omitted by someone tightening a paragraph who never intended to change the meaning.
And do not paraphrase a caveat that was written carefully. Rewording is where "not significant on its own" becomes "close to significant".
Check
Try to write the number without the caveat and watch it fail. Delete the qualification argument, or put a bare figure in a page, and run the build.
If it compiles, the pairing is a convention rather than a mechanism, and conventions survive exactly as long as nobody is in a hurry.
Risk
Over-applied this makes ordinary reporting heavy: not every number is a benchmark, and a caveat on a figure that does not need one trains people to skip caveats.
The harder risk is that a mechanism feels like the whole answer. A component that always renders some caveat does not check whether the caveat is the right one. The sentence still has to be written honestly by a person; this only stops it from being dropped afterwards.
Use it
The card is data. Clone the repository and import it by path — anything that arrives over the network is treated as tainted and held for approval, which is the behaviour you want and the reason there is no one-line installer here.
git clone https://github.com/brcampidelli/chimera-agent.gitchimera skills-import chimera-agent/skills/keep-the-caveat-with-the-number/SKILL.mdIntegrity
SHA-256 of the file as published. An importer can check that what it received is what this page showed.
297f015e113d1ef9605a20543b933b1e75107318c5b15149fe353b05e34676b2