I use loops to finish the documentation, too
A writing pass, an adversarial review, and a correction pass give my coding agents usable instructions before implementation starts.
Published 2026-08-27
Loading content...
A writing pass, an adversarial review, and a correction pass give my coding agents usable instructions before implementation starts.
Before I run an implementation loop, I use separate passes to write task documents, review them for contradictions, and apply corrections. The reviewer leaves comments so I can distinguish a proposed change from an accepted product decision.
Once I've talked through a project and moved the requirements into files, I usually have enough information to describe the product. I don't necessarily have enough information for an agent to build any individual piece without making several decisions along the way.
Some of those decisions are fine to leave to implementation. Others change what the product does. I want to sort those out before several workers start building different interpretations of the same feature.
So I use loops for the documentation before I use them for the code.
I start with a worker reading the central task list. For each item, it follows the links back to the source requirements and writes a focused document describing what needs to be built for that step.
I want enough detail for a fresh implementation session to get started. The document should identify the relevant product requirement, the behavior being added, any earlier work it depends on, and how we'll check it. For an existing codebase, it should also point to the code or conventions the worker needs to inspect.
It doesn't need to prescribe every line of code. A task document can become just as speculative as an implementation if I ask for too much detail before the relevant code exists.
Here's an example instruction for the writing pass:
Take the next undocumented item. Read its source requirements and
dependencies, then write its task document. Include observable behavior,
acceptance checks, and unresolved questions. Label assumptions explicitly.
If a product decision is missing, record it as unresolved instead of
inventing the answer. Update the item's documentation state and continue.
This is still one worker doing one item at a time. It can run for a long time without needing to turn the entire product into a single enormous response.
The next agent gets an adversarial review job. I ask it to find holes, conflicts, and assumptions unsupported by the original requirements. It reads across the task documents, including the earlier steps, to see whether they fit together.
For example, imagine a hypothetical multiplayer game spec where one task allows the host to create new villagers, while another only describes updating villagers already present on a joining client. Either document might look complete by itself. Read together, there's an unanswered question about how a newly created villager reaches the other player.
The useful review comment names both documents, describes the missing behavior, and explains what needs resolving. "Improve multiplayer reliability" doesn't help much.
I usually ask this agent to leave comments in a separate review file instead of changing the specs. Its job is to build up an understanding of how the documentation fits together. If it starts rewriting requirements as it goes, a plausible suggestion can become the new source of truth before anyone has evaluated it.
The review notes also need to survive outside the chat. Otherwise I've recreated the same context problem with a more impressive collection of documents attached. A replacement reviewer should be able to see which findings remain open and which were already addressed.
Then another worker loops through the findings and updates the documentation. It should read the source material before accepting a proposed correction. An adversarial reviewer can be wrong, too.
For each finding, I want a recorded outcome. It was applied, rejected with a reason, or left unresolved because it needs a decision. If the correction changes an interface used by a later task, the dependent document needs attention as well.
I consider the documentation ready when the items in scope have usable specs and the blocking findings have been resolved. Running the editor through the list isn't enough if it leaves a product question unanswered. Changed documents may need another review; unaffected ones don't need to be rewritten for the sake of another pass.
For a small feature, I can do all this with separate prompts in one sitting. For a larger project, separating the workers helps keep the jobs clear.
I expect implementation to expose mistakes in the documentation. That's fine. The worker should record the discrepancy and update the relevant spec when the evidence supports a correction, keeping the product requirement intact.
There are also decisions I don't want settled by another documentation pass. Whether a screen feels crowded or an interaction makes sense is often easier to judge by using it. I put those human checkpoints into the task documents so the loop produces something I can review while there's still time to change direction.
Once the next task has a usable spec and a check I can run, I can start building it. I'll update the document if the implementation exposes something we missed.