Agents should show their working

The first version of our release agent worked beautifully and nobody used it. It read the note, read the pull requests, wrote a changelog entry that was frankly better than ours, and presented it as a finished thing.

Every single person edited it from scratch. Not because it was wrong — because they had no way to tell whether it was wrong.

Trust is a function of legibility

You cannot check a paragraph against your own memory of twelve pull requests. What you can check is a list: it read these three PRs, it skipped that one because it was a revert, it took the wording from the last four entries. Given the list, the paragraph either follows or it does not, and you can tell in four seconds.

So we rebuilt the agent around its log rather than its output. Every step it takes is a row: what it read, what it decided, what it chose not to do. The draft sits underneath, as the last row.

The rule we ended up with

An agent may not take an action whose reasoning it cannot show. This sounds obvious and it is expensive: it rules out a whole class of clever shortcuts where a model does five things at once and reports one.

What it buys is the only thing that matters here. Editing rates on agent drafts went from ninety-four per cent to under a fifth, and the drafts did not get better. They got checkable.

What we still get wrong

Agents are bad at knowing when a note is not for them. A note that says this feels off is a request for a person, and we ship a version every few weeks that is a little better at leaving those alone. It is the failure mode we watch most closely, because an agent that answers a question nobody asked it costs more attention than it saves.