Mostly Done.
Contents

6 Write the disagreement before the code

Coding agents make implementation cheap enough that you are tempted to start there. A request arrives, the agent reads the repository, and a plausible patch appears before anyone has stated the hard decision. This feels fast until the patch gives the wrong model a few hundred lines of momentum.

The remedy is a gate before nontrivial code. Call it a brainstorm, a spec, a design, a plan. The artifact can be a page or a paragraph. Its job is always the same: give yourself something inexpensive to disagree with.

6.1 Find the decision that can invalidate the patch

Consider a workflow design sent through five reviewers, each with a different concern: control flow, checkpoint and resume behavior, audit integrity, simplicity, tests. One reviewer found that a gate which never ran could still be counted as covered. That was a state-model error, not a typo. In the design it cost a few sentences to repair. In code it could have produced a complete implementation, a matching test suite, and a confident completion report built on the same false premise.

Some errors run deeper than a repairable state model. Consider a shipped migration that converted a node’s retry destination into a routing edge. A later design investigation established that retry and routing are distinct channels in the runtime that consumes the workflow, so no refinement of the conversion could be correct. The right change was to keep retry and fallback destinations as node fields and revert the premise of a feature that had already shipped. No clever implementation could save the model, because the model itself was the defect.

A useful design gate asks which decision could make the whole patch wrong even if every line is clean. Typical candidates:

These questions belong before implementation. Once code exists, authors become invested in preserving it. That is true for people and for models.

6.2 Scale the design to the risk

Design first does not mean a miniature standards process for every edit. The size of the document should follow the amount of judgment in the change.

A two-line geometry adjustment may need four sentences:

  1. the visible defect;
  2. the intended geometric rule;
  3. the state that must not change;
  4. the check that will fail on the old behavior.

A parser feature, persistence change, migration, or new projection model deserves more. It should identify the canonical state, failure behavior, compatibility policy, proof obligations, and rollback boundary.

The gate becomes theater when it rewards document length rather than exposed decisions. It becomes useful when implementation cannot begin until the author has answered the question most likely to invalidate the work.

When the design survives, its trail can stay inspectable. A feature can run from a dated design document through a plan, a series of implementation commits, review fixes, and a tagged release, each step a named artifact you can reopen later. The design yields a durable decision and a decomposition, not one large execution unit. Not every feature needs that much ceremony, but ceremony done this way leaves evidence instead of meeting minutes.

6.3 Remove the gate that cannot change the outcome

The lesson cuts the other way too. Suppose your process includes a standing pause for your own detailed review, while your repository policy already delegates detailed review to independent review agents. Once that policy stands, the pause cannot change the work. It is ceremony. Delete it.

Sort your gates into three kinds:

The distinction is not whether the gate agrees with the recommendation. A gate can wave the recommended choice through and still be working, provided the choice carries a genuine blast-radius tradeoff and a different answer would have redirected the work. Ask whether disagreement was possible and would have mattered. If not, delete the pause.

6.4 Put human attention at the fork

You need not prescribe each helper function or file edit. That would throw away the agent’s main advantage. Your attention is better spent on forks that encode product intent, acceptable loss, or cross-project reality.

A good fork might ask:

The agent can explain the consequences. You choose the policy. After that, execution can be delegated widely without leaving the important semantic choice implicit.

6.5 Review the design to break it

A design review should not ask whether the proposal sounds reasonable. Almost every flawed design sounds reasonable when summarized by its author. Give each reviewer a specific lens and a request to find a counterexample.

Useful lenses include:

Disagreement between reviewers is often the valuable part. Put two reviewers on a workflow state model and one may argue that an explicit clear operation is unnecessary while the other shows why looping workflows require it. The conflict forces the state transition into the open, and the decision follows the behavior, not the vote count.

6.6 Keep the design after the merge

Do not discard the design when the code lands. It becomes one of three things:

The document should not narrate the diff forever. It should preserve the decision that a future agent might otherwise reverse by accident.

The best design gate is modest. It catches a wrong idea while changing the idea is still cheap.

use ← and → to turn pages