Writing
Cold reads: checking an agent's task before it builds
Before a coding agent builds a task in Cat Herder, a fresh agent reads it the way the worker will. A strict pass rule kept tasks going round, so it changed to one read on a model sized to the task.
Cat Herder runs many coding agents on one repo, with the work kept as a queue of tasks in git. A planner agent writes each task, a worker agent builds it, and a reviewer agent gives the verdict.
The weak point in that chain is the hand-off. The planner knows the conversation that produced a task; the worker gets only the text. When the text is unclear, the worker guesses, and a wrong guess usually shows up only at review, after the build.
A cold read checks the text before the build. Before a task is marked ready, a fresh agent that has seen none of the planning reads the task and the code it names, the way the worker will. It changes nothing, runs no tests, and reports what is unclear or wrong. A worker can claim a task only once it is ready.
What a cold read asks
The reader looks for the ways a worker could misread the task:
- Ambiguity: a word used two ways, or a term never defined.
- Contradiction: a later note on the task that disagrees with its body.
- Overlap: another open task touching the same code.
- Checks that prove nothing: a “Done when” point that already passes on today’s code.
If I could keep only one, I’d keep the last, because a check that already passes doesn’t test the change.
Each finding gets a severity by what it would cost the worker: high if they’d build the wrong thing, medium if they’d have to guess, low otherwise. The exact brief ships with Cat Herder, for anyone who wants to copy it.
Two catches
Catch 1: most of the work was already done. In late October a task asked for the status card to print when a session newly stalls.
- The read found that the card already did that, and that one of the task’s checks would pass on today’s code.
- The task shrank to the one missing test.
Catch 2: the fix aimed at code the release didn’t call. In early November a task meant to fix a function called swap().
- Nothing on the release branch called it. The real path went through
swap_all. - The task was rewritten to fix that path before anyone built it.
Every rule came from something that went wrong
Adding a rule only when something breaks is the right habit, and it’s also how rules pile up.
- A worker built from a stale body. A later correction had changed the task, and the worker followed the original. Since then, one current spec section says what to build now.
- A task changed after its read, then went ready. Now a task can’t go ready without a cold read newer than its last change, and the queue can enforce that.
- Reads let through tasks a worker would still have to guess at. I added severity tags and passed a task only with no high and no medium finding. That one went too far.
- Big tasks still came back wrong after two reads. They now get a heavier spec pass first: a caller map, clarifying questions and a contradiction check.
Fixing every medium made tasks worse
Under it, a medium finding had to be fixed before a task could pass. The fix was a correction added to the task, and the next read often flagged the correction, so each round left the task longer and harder to read. One task went through read after read until I called it unreadable and split it into clean tasks.
One read, sized to the task
The rule now:
- Each task gets one read, and only a high finding holds it back.
- A high is fixed by rewriting the task’s current spec, never by stacking another correction, and then gets one fresh read.
- Medium and low findings go to the worker and reviewer, who settle them before the build.
- Readers no longer flag how the code should get there; that is the worker’s call.
The reader’s model now follows the task:
- Haiku 5.5: a small, clear change.
- Sonnet 5.5: a medium task, a defect, or a small change to shared code.
- Opus 5.5: large work, and medium or larger changes to shared code.
- Step up: a read that raises a high, or three or more mediums, moves the next read up one model.
A change to shared code gets a stronger reader than its size alone would earn, because a wrong build there reaches everything that calls it.
It costs fewer reads per task (about one where it was three, though that is an estimate until it has run a while), and costlier reads for tasks that touch shared code. The benefit isn’t measured yet. The rule is new this week, and I don’t know what it misses.
What the numbers show, and what they can’t
More than five hundred tasks have had a cold read. The typical one took about three reads, and the worst took eighteen, counting reads from before the strict rule. About two reads in five raised at least one high finding, probably an overcount, since the count also picks up severity labels on points that were already answered.
None of that says what the reads prevented, because every task got one, and there is nothing to compare against. The closest thing is a pattern: in nearly two hundred tasks, a read found something high, a later read found nothing high, and the task was finished. A check that catches real problems leaves that pattern, and so does a check that flags harmless ones, and reads do flag harmless ones. On the day the new rule started, a Haiku 5.5 read raised two highs against a copy of the repo dozens of commits behind; on the current code both were false.
Next I want a comparison group. Over a few months, small, self-contained tasks will be split at random: half get a cold read as usual, and half get one that the worker never sees. Within weeks, the hidden reads should show whether what they flagged is what actually went wrong, and how often a high was a false alarm. Comparing send-backs between the two halves takes the full run. Larger tasks and ones that touch shared code keep their reads.
What ships in Cat Herder
- For anyone who uses it: the reader agent, the cold-read workflow (a script that starts the readers side by side) and its five-question brief, the command that records a read, the refusal to mark a task ready without a fresh read, and the refusal to mark a strict task ready without the spec pass’s three sections.
- My own process, for now: the pass rule, the model sizing, when the spec pass is due, and Spec Kit for doing it.
- Next: the model sizing is queued to become part of Cat Herder once the workflow can be told which model to use.