When writing it down is the wrong move

The counterweight this module needs

Everything so far argues for writing more down. That argument has a limit, and a course that does not state the limit produces people who write a design document for a two-line fix and slow their team down while feeling rigorous.

Specification has a cost: your time, the reader’s time, the maintenance burden, and, the one people miss, the risk of committing to a design before you have learned enough to choose one.

The test

Write it down when a wrong guess would be expensive or invisible.

Both halves matter. Expensive covers money, permissions, deletion, another company’s system, anything a regulator reads, anything that sends a message to a human. Invisible covers the cases where being wrong produces no error: a rounding rule, a tie-break, a timezone assumption, a fee applied at the wrong point.

A wrong guess that is cheap and loud needs no specification. You will find out in four minutes and fix it in two.

Where writing it down is actively wrong

Exploratory work. When you do not yet know whether something is possible, the fastest way to find out is to try it. A specification written before you have any evidence is a guess with a formatting. Spend the two hours on a spike, throw the code away, and then write the specification with what you learned. The order is: explore, decide, specify, build.

When the code is the shortest correct description. For a pure function with a clear name and three parameters, the signature and one test express the requirement more precisely and more briefly than any prose could. Prose here adds a second thing to maintain and no information.

Genuinely reversible decisions. Which of two very similar libraries, what to name a private helper, the internal structure of a module nobody else imports. Decide, ship, change it later if wrong. Writing a record for these dilutes the records that matter, and a folder with two hundred decision records is one nobody reads.

When you are the only reader and it is finished today. Notes in a scratch file are fine. Not everything is an artefact.

The middle case, which is most cases

Most work sits between the two-line fix and the payments rewrite, and the right answer is a specification of about six lines in the pull request description or the ticket.

Adding stock reservations. Reserve on add-to-cart, expire after 20 minutes.

Expiry is checked lazily on read, not by a background job: we do not want

another scheduled process for v1.

Out of scope: partial reservations, back-orders, the warehouse sync.

Open question: what happens to a reservation when the price changes?

Decided with Priya: reservation holds quantity only, not price.

That is ninety seconds of typing. It names the design, the deliberate simplification, the boundary, and the one question that came up, including who answered it, which is the detail that saves an argument in March.

The honest observation is that six lines like these deliver most of the value of specification and almost none of its cost, and that the failure mode on most teams is not over-specification. It is nothing at all.

The three questions that decide it

Before any non-trivial change, answer these. If all three are quick, write nothing.

1. Would two competent engineers build this differently from what is written? If yes, write more.
2. If this is wrong, when do we find out? If the answer is longer than a week, write more.
3. Will anybody ask why this is like this? If yes, write the why, and only the why.

That third question is the one that most reliably identifies the sentence worth writing. Not what the code does; what would look like a mistake and is not.

The trap to avoid at the other end

There is a specific failure mode that has appeared with these tools and it is worth naming.

Because a model will happily produce a twelve-page design document in a minute, teams start generating them, and the volume of specification goes up while the amount of deciding stays the same. A document that nobody made choices in is not a specification. It is a description of the space of possibilities, phrased confidently.

The value of a specification is entirely in the decisions it contains: the alternatives foreclosed, the ambiguities resolved, the boundary drawn. Those come from a human with context, they take the time they take, and there is no version of this that is fast.