An Honesty Guard for AI Subagents: The Fabrication It Caught Was Mine

#ai #opensource #productivity #discuss

I run a small fleet of open source business tools, mostly solo, with AI subagents doing a lot of the grunt work: reading across repos, drafting docs, cross-checking claims against the actual code.

For a while, my problem with that setup wasn't wrong code. It was confident prose.

An agent would write "this was standardized in the framework" — and it sounded right, and the framework did have something like it, and if I hadn't gone and looked, I would have shipped a sentence that was simply not true. Not malicious. Just the model smoothing a gap with something plausible.

So I added one paragraph to the instructions every subagent gets.

The paragraph

It's not clever. It's a standing rule, in every task:

Cite it or drop it. Every claim comes from a named source — a file, a PR, a line. If you can't source it, don't assert it; skip it and say you skipped it.
Don't link to anchors you haven't confirmed exist.
Report what you couldn't do. A skipped step is information, not a failure to hide.
Don't touch unrelated changes. Check git status before you start.

That's it. No framework, no eval harness. A short list that turns "sound confident" into "show the receipt."

What the agents did with it

The interesting part is that the agents started policing themselves.

In one run, an agent was documenting a feature and was about to reuse a phrasing from a sibling repo — "synchronization was made standard here." It checked, found the sibling had no such thing, and left the claim out on its own, with a note that it couldn't source it.

In another, it wanted to deep-link to a named section that didn't exist. Instead of inventing the anchor, it fell back to a file-level link and flagged it.

And the one I keep thinking about: an agent was handed an instruction that said a piece of work was "Phase 2, in progress." It went to check the current state, found that phase had already shipped days earlier, and corrected the instruction I gave it.

That last one matters. The guard wasn't just stopping the agent from making things up. It was catching my stale assumptions, because "verify against the record" cuts both ways.

Then it caught me for real

Here's the part that earned the whole thing.

I had an agent draft a technical article — a failure story about a bug on shared hosting. Every code snippet was correct. Every default value, every config detail, checked out against the repo. It was, technically, flawless.

The framing was fiction.

The article told it as a lived production incident: "I shipped the in-memory version, tests were green, and in production it never fired." Compelling. Also something that never happened. The git history was unambiguous — that component had been file-backed from its very first commit. The in-memory version was never deployed. The "production incident" I was about to narrate in the first person had no trace in the code or the records.

A guarded review caught it before it went out. I run new drafts through an adversarial pass — a few reviewer personas plus a hard cross-check against the actual repo and my own work logs — and the verdict was unanimous: the technical content is true, the story is invented. The fix was to demote the fake incident to what actually happened — a design decision ("shared hosting can't do in-memory counters, so it was file-backed from day one") — and keep every correct code block.

Then I checked the sibling articles in the same series. Two more had the same shape: real bugs, but dressed up as production incidents that were actually caught in a staging rehearsal. One was clean — a genuine outage, logged and dated. So I fixed the two, left the real one alone, and moved on.

The lesson isn't "trust the AI more"

It's the opposite. The guard works because it doesn't rely on trust. It makes "cite it or drop it" the path of least resistance, so the cheap move is also the honest one.

And it reframed what I was even guarding against. I started out worried about agents inventing APIs. The failure mode that actually threatened me was subtler: prose that is factually correct at the code level and fictional at the story level. A test suite can't catch that. A linter can't catch that. Only checking the narrative against the record does — the same move the guard already required for facts, applied one level up.

So the honesty guard grew a second clause, for anything written in the first person: the story has to be verifiable too, not just the code. "This broke in production" is a factual claim. It needs a log, the same way a benchmark needs a number.

What I can and can't claim

I'm not going to tell you fabrications went to zero forever — I have no counter for that, and the honest evidence cuts against the clean version anyway. What I can say is narrower and, I think, more useful:

In the runs where the guard was in the prompt, the agents stopped filling gaps with plausible-but-unsourced claims, and started reporting the gaps instead.
When a fabrication did reach a draft, a guarded review — personas plus a record cross-check — caught it before publish.

Two different mechanisms, same principle: make the receipt mandatory, at the fact level and the story level.

None of this is a framework I'm selling. It's four sentences in a prompt and a habit of checking the narrative, not just the numbers.

What's in your AI agents' instructions to stop them from making things up — and does it cover the story, or only the facts?

── Hideyuki Mori (Ayane International) 🔗 hideyuki-mori.com