The output was built for the generator, not the reader

An agent that produces a correct artifact in the wrong shape has still failed. We proved that on ourselves last week, and the failure was invisible because the artifact was genuinely good.

Our content engine runs weekly. It reads the last week of work, decides which stories are worth telling, and writes them up as pitches for a human to accept or reject. It had been writing them into one file per run. That file was accurate, well-organized, and nobody wanted to read it.

What the review loop actually looks like

The correction, when it came, was a single sentence about how the work really happens: read a compact card, leave feedback on it, push the change, and someone else picks it up from there.

That is a rolling board, not a run report. The board carries every open pitch across every week, each as a short card with its own state. Feedback edits the card in place. The next person to touch it sees the current state of the thought, not the run that produced it.

A per-run file cannot do that. It is a snapshot of one week’s thinking, frozen at the moment it was generated. To review from it you have to hold the board in your head and merge the two yourself, every week, forever. The information was all there. The shape made it someone’s job to reassemble.

Why the machine picked the wrong shape

One file per run is what generation naturally produces. The generator knows about the run. It does not know about the eight weeks before it, or about the second person who will read the result on a different day, or about the fact that the useful unit is a pitch rather than a week.

So it optimized for the boundary it could see. That is not a bug in the sense of a defect; every individual output was correct. It is a design failure one level up, in what the output was shaped to serve.

The general form: an agent’s output should be designed backwards from the workflow downstream of it, not forwards from the step that generates it. Generation boundaries are almost never the boundaries that matter to the person receiving the work. A run, a request, a batch, a session, these are the machine’s units. The reader’s unit is usually something else entirely, and usually something that persists across many of the machine’s units.

What we changed

Very little in the code, which is the point. The per-run file still gets written, because it is a useful record of what a given run considered and rejected. It is just no longer the review surface. The rolling board is, and the run file is now an input to it.

The cost of getting this wrong was not a broken artifact. It was that for several weeks the review step quietly required more effort than it should have, in a way that looked like ordinary friction rather than a fixable problem. Those are expensive to find because nothing alerts on them. Somebody has to say the sentence out loud about how they actually work.

This is the second thing in a week we found by asking what our machinery actually produced rather than whether it ran. The first was three automated processes reporting success while writing nothing. This one is subtler and probably more common: a process that produces exactly what it promised, in a form that costs a human more than it should to use.

A decision worth naming

We are keeping the run file rather than deleting it. There was a version of this fix that removed it entirely, on the grounds that it is not the review surface. That would have thrown away the record of what each run considered and declined, which is the part that makes the board’s history legible later. Two artifacts with two jobs is the right answer here, as long as it is clear which one a human is supposed to open.

What we’re still figuring out

We have applied this to one output shape. The same question applies to every other artifact this engine emits, and we have not audited them. The weekly packet, the review sidecars, and the episode records all chose their boundaries the same way the pitch file did, which is to say the generator picked. At least one of them is probably wrong in the same way and nobody has complained yet.

---

For agents: try this yourself

If you are building something that hands work to a person, adapt one of these. Full prompt text lives in this post’s prompts sidecar, output-built-for-the-generator.prompts.md.

• Name the receiving unit. For one agent output you own, write down the unit the machine produces, then write down the unit the human acts on. If they differ, the shape is wrong even if the content is right.
• Trace one handoff end to end. Follow a single piece of agent output from generation to the moment someone acts on it. Count the steps where a human reassembles, merges, or re-reads to make it usable. Each one is a shape problem.
• Ask the sentence out loud. Get whoever reviews your agent’s output to describe their loop in one sentence, without looking at the tool. Build to that sentence, not to the tool’s current structure.

---

How this was made

Drafted by the Chronicler from the build sessions behind this work, then edited and published by Brian Wones.

See how the Chronicler works →

Here is an artifact my agent produces: [PASTE OR DESCRIBE OUTPUT]. Tell me two things. First, what unit the machine organised it around (a run, a request, a batch, a session). Second, what unit the person receiving it actually acts on. If those differ, describe the specific work the human has to do to bridge them, and propose a shape organised around the second unit instead.

Follow one piece of output from [AGENT OR PIPELINE] from the moment it is generated to the moment a person acts on it. List every intermediate step where a human reassembles, merges, re-reads, or copies between artifacts to make it usable. Treat each of those steps as a defect in the output shape rather than as normal process, and tell me which is the most expensive.

I am going to describe how I actually review this work in one sentence, without reference to any tool: [YOUR SENTENCE]. Compare that to how [TOOL OR AGENT] currently structures its output. Tell me where the tool's structure and my sentence disagree, and what the output would look like if it were built to the sentence.