The most valuable sentence in an agent system's documentation is usually the one admitting what it can't do yet. It's also the sentence most likely to get cut before anyone else reads it. That deletion is where trust goes to die.

Thesis: "It works" is not a fact — it's a claim with a scope, and the scope is the whole story. Agent systems (and the people who build them) overclaim by reflex: a demo becomes "proven end to end," a passing battery becomes "verified," an asserted rule becomes an enforced one. Candor about the gap isn't a disclaimer you bolt on at the end. It's the central discipline — and it's the thing that makes everything else you say believable.

This is the final post in the "Intent Over Instructions" series. The clean room was about proving the work. This one is about the harder, more human problem: honestly saying what you proved — and what you didn't.

The Overclaim Reflex

There's a well-known failure where an LLM declares a task complete that isn't. It's mundane and constant: the model says "done," the tests were never run, the edge case was never handled. We've built whole layers of enforcement around it because documentation alone never stops it.

The builders of agent systems have the exact same reflex, and it's less examined. A single successful demo becomes "proven end to end" in the README. A battery that checks output format becomes "verified" in the changelog. A safety rule written in a design doc becomes, in conversation, a rule the system enforces — when in fact no code enforces it at all. Each of these is the same move: quietly widening the scope of a claim past what was actually established.

The tell is always a scope-free verb. "Works." "Verified." "Handles." "Proven." Works on what inputs? Verified against what? Handles which cases? A claim without a scope isn't a strong claim — it's an unfalsifiable one, which is worse.

"Works" Has a Scope — State It

The most honest agent docs I've read read almost like disclaimers, and they're stronger for it. One system I worked from draws a hard line through the middle of the word "verified": it is "verified before it runs" only for reads. Writes — the actions that actually change the world — are the unproven part, and the docs say so in the same breath as the claim.

That system went further and forbade a phrase. The words "proven end to end" were banned from the docs until a gated external write actually succeeded — because the flagship write had, in truth, never once fired successfully (it timed out). Not "mostly works." Not "works, with a known issue." The specific, load-bearing claim "proven end to end" was treated as a lie until the specific event it names had actually happened.

flowchart TD
    Claim["A claim you want to make"] --> Q{"What did you<br/>actually observe?"}
    Q -->|"read path succeeded"| R["Say: 'verified for reads'"]
    Q -->|"one demo succeeded"| D["Say: 'demonstrated once,<br/>on this input'"]
    Q -->|"format checks passed"| F["Say: 'format-verified,<br/>behavior ungraded'"]
    Q -->|"a gated write fired<br/>and was confirmed"| E["Now you may say:<br/>'proven end to end'"]

    style R fill:#5a5a8a,color:#fff
    style D fill:#5a5a8a,color:#fff
    style F fill:#5a5a8a,color:#fff
    style E fill:#2d6a4f,color:#fff

The discipline is to match the verb to the evidence. If reads are proven and writes aren't, "verified" without qualification is false. Say "verified for reads." It's less impressive and completely true, and the reader now knows exactly where the edge is.

Keep a Ledger of Your Own Lies

Here's the practice that impressed me most, and the one almost nobody does: a de-bias ledger — a standing document that lists the system's own past overclaims, each paired with its correction.

Not a changelog of bugs. A changelog of things we said that weren't as true as they sounded. Entries like:

  • "Proven end to end" — the flagship write never actually fired; it timed out. Claim retracted.
  • "576 tests passing" — some of those tests were circular goldens asserting output against an empty buffer. Number is real; the reassurance it implied was not.
  • Confidence 1.0 — emitted on garbled input. The number is not a calibrated probability and must not be read as one.

Writing this ledger does something no amount of feature work can. It tells the reader: this author catches their own inflation. Which means the claims that don't appear in the ledger — the ones the author let stand — are load-bearing. Candor about past overclaims is what earns belief in present claims. A doc with a self-correction ledger is more trustworthy than a doc with none, even though the second one looks cleaner. Especially because it looks cleaner.

The Most Dangerous Gap: Asserted but Not Enforced

There's one overclaim that's worse than all the others, because it hides inside something that reads like rigor. It's the safety rule that is stated but not enforced.

A system had a privacy invariant: sensitive data must be redacted before it leaves the machine. It was written down. It was called a requirement. And in the shipping version, no code enforced it — the redactor existed only in an archived prototype. So the test battery cheerfully sent unredacted sensitive data to a hosted endpoint, in full compliance with a rule that was real on paper and absent in fact.

flowchart LR
    subgraph asserted["Asserted only"]
        A1["Doc: 'PII is redacted<br/>before it leaves'"] --> A2["No enforcing code"]
        A2 --> A3["Reader believes it's safe.<br/>It isn't."]
    end
    subgraph enforced["Enforced"]
        E1["Doc: 'PII is redacted'"] --> E2["Blocking gate in the<br/>egress path"]
        E2 --> E3["Reader believes it's safe.<br/>It is."]
    end
    style A3 fill:#9d4444,color:#fff
    style E3 fill:#2d6a4f,color:#fff

The design note names it exactly: "a safety invariant asserted but not enforced is the most dangerous kind of gap" — more dangerous than an acknowledged gap, because acknowledged gaps make you cautious and asserted-but-absent ones make you confident. The honest move is a status table that separates, for every guarantee, "documented" from "enforced by code." Anything in the first column but not the second is a claim you haven't earned, sitting where a reader will assume you have.

This is the reporting-side twin of the clean-room lesson: if it matters, it has to be structural, not stated — and if it's only stated, your writing must say so out loud.

Even "Verified" Has an Edge

Push on the strongest word and it still has a boundary. Verify-by-effect — the gold standard from the last post — proves that the intended effect happened. It does not prove the absence of other effects. A verified write to a Slack channel confirms the message posted; it says nothing about whether the same action also exfiltrated a token on the side. "Verified" means "did the thing we checked for," not "did only that thing and nothing else."

You don't have to close every such gap to be honest about it. You have to name it — "we verify the intended effect; we do not currently detect unintended side effects" — so the reader calibrates correctly. The alternative, letting "verified" carry more weight than it earned, is how a real limitation becomes an invisible one.

Honest Status Beats Impressive Status

The habit that ties it together is small and unglamorous: mark the real status of everything, in-line, where the claim lives.

The best examples I've seen are almost curt about it. A capability the design describes in detail is annotated "still named, not built." A safeguard is labeled "guidance, not a wall" — it advises, it doesn't block, and the sentence tells you which. A design choice is tagged "an open question, not a decision." A known problem sits under a heading that says "flagged but NOT fixed (deliberate)."

None of that is impressive. All of it is trustworthy. And the trade is heavily in candor's favor: an "open question, not a decision" costs you a little shine and buys the reader an accurate map. An unmarked open question dressed as a decision saves the shine and detonates the first time someone builds on it.

There's a version of this that a static grader can't catch and only candor can: a skill that never fires. A skill can pass every behavioral test and still be shadowed by a broader sibling so it never actually triggers in practice — "the failure that matters most." A status note that says "triggering unverified in the live selector" is worth more than a green test suite that quietly assumed the thing it was testing had even loaded.

When Polish Wins

That instinct to mark status everywhere can tip into overcorrection, though: candor is the default, but it isn't the only value, and there are places to lead with the clean version:

  • A landing page or a pitch isn't the venue for the de-bias ledger. Lead with what works; link to the honest status doc. Hiding it would be the sin; making a visitor read it first is just bad editing.
  • Stable, boring, genuinely-done things don't need a caveat on every sentence. Reserve the scope-tags for the load-bearing and the not-yet-true. Caveating the sunrise trains readers to skip your caveats.
  • Internal vs external audiences differ in detail, not in honesty. The ledger can be terser outside; it can't become fiction.

The line: polish the presentation, never the scope of the claim. Make it beautiful. Don't make it say more than happened.

What to Do Next

  • Hunt your scope-free verbs. Search your docs for "works," "verified," "handles," "proven." For each, write the missing scope — on what, against what, which cases — or downgrade the verb until it's true.
  • Split "documented" from "enforced." Make a two-column table of your guarantees. Anything asserted without enforcing code is your highest-priority gap — fix the code or flag the claim.
  • Start a de-bias ledger. List the last three things you said that were rosier than reality, each with its correction. It will feel bad and read as strength.
  • Forbid the phrases you haven't earned. Pick your "proven end to end" — the specific claim you're tempted to make early — and ban it until the specific event it names has actually, observably happened.
  • Mark status where the claim lives. "Named, not built." "Guidance, not a wall." "Open question, not a decision." In-line, next to the thing, every time.

This concludes the "Intent Over Instructions" series. The arc: bound the task by outcome, write instructions lean enough to outlive the model, bind the goal and let the how re-resolve, gate autonomy on more than a confidence score, verify in a clean room the maker can't touch, and — finally — say exactly what you proved and nothing more. Decouple the what and the why from the how; then be honest about how well the how actually worked.