The Spec Has to Close the Loop

Teams have always written requirements. They have also watched those requirements lose authority one conversation at a time. A developer makes a reasonable interpretation, a reviewer accepts a nearby behavior, and production teaches everyone what the feature actually means. The document remains pristine while the system moves on without it.

Putting an agent between the document and the code does not fix that. It makes the gap faster. A detailed markdown file can produce a plausible plan and a large implementation, but it is still just context unless the factory can prove which requirement became which behavior. Structure helps an agent read. It does not create authority by itself.

A specification earns authority when it changes what the line may do. It defines the observable outcome, the boundaries that cannot move, and the evidence required to leave each stage. If the builder can ignore it, the tester cannot trace to it, or the release can pass without it, you have better documentation—not a control plane.

A useful spec keeps three decisions apart. Intent says what must become true for the user or the business. Design says how this system will make it true. Permission says which constraints still hold while the work happens. Collapse those together and every implementation detail starts masquerading as a permanent requirement.

That separation matters because the parts change at different speeds. The outcome may stay fixed while an interface, dependency, or model changes. A security boundary may remain nonnegotiable while the plan is rewritten completely. When the spec names those layers, an agent can revise the method without quietly renegotiating the destination.

People still own these choices. Human judgment decides which outcome is worth pursuing, which tradeoffs are acceptable, and which consequences demand a stop. But people should not have to restate those decisions in every review. Once the boundary is settled, the factory should apply it on every run without waiting for the right person to remember it.

A link from a ticket to a pull request is bookkeeping. Operational traceability is stronger. The factory should be able to show which acceptance condition produced a test, which changed surface satisfies it, and which proof allowed the work to advance. A missing link should stop the route, not create a task for somebody to clean up later.

That is how you escape code review as the universal safety net. Reviewers cannot reliably reconstruct intent from a giant generated diff, and asking them to do it wastes the leverage the agent created. Give an independent verifier the specification, the changed behavior, and the allowed boundaries. Let it reject work that is internally tidy but answers the wrong question.

The hard case is extra behavior. Agents are productive enough to add useful-looking abstractions, utilities, and options that nobody requested. A working test suite can bless all of it. The specification must define the permitted change surface so the factory can treat unrequested capability as a failure rather than a bonus.

The loop is not closed when the code ships. Production can disprove the framing, expose a missing constraint, or reveal that the requested concept bundled several different policies together. If that evidence only becomes a patch, the specification stays wrong and the next agent begins from the same bad map.

Route each failure back to the artifact that permitted it. A misunderstood outcome changes the work specification. A repeated architectural mistake changes repository context. A risky action changes the permission policy. A missed behavior becomes a reproduction test tied to the requirement it refines. The correction should reach every later run, not just the person who handled the incident.

This is also why rewriting generated output forever is a dead end. The human fix may rescue today's branch, but it teaches the factory nothing unless the responsible instruction, control, or proof changes with it. Recovery that leaves the route untouched is recurring labor wearing the costume of progress.

Do not begin by converting the whole backlog into elaborate templates. Pick one repeating change whose result can be observed. Write the intended outcome, the forbidden moves, the acceptance examples, and the evidence needed to release it. Then make planning, implementation, verification, and observation point back to those decisions.

Run the loop and inspect where correspondence breaks. Did the plan cover every outcome? Did the tests prove behavior through the real interface? Did implementation introduce work outside the boundary? Did production evidence reach the next specification? Those questions tell you whether the spec governs the system or merely accompanies it.

Our position is that specification work will become one of the highest-leverage forms of software engineering as agents take over more implementation. That does not mean the future belongs to people who write the longest documents. It belongs to organizations that can turn judgment into a living route, prove the route held, and feed reality back into the next run. The spec matters because the loop closes.