05 The decision log

05 · The decision log

Every substantive choice made during the iterative process enters the specification as a numbered decision: a stable identifier, the statement of the choice, and its rationale. Decisions can be cited by number, in later conversations and in linked documents, without reopening the discussion.

It is the practice software knows as architecture decision records, in use for over a decade in organisations of every scale; but recording decisions with their rationale is not specific to software — it is what every minute of resolution, every note of direction, every project log attempts to do. The value lies not in recording the choice, but in recording its why and the trade-offs accepted. A decision without a rationale loses value over time: whoever encounters it months later has only two options, to accept it blindly or overturn it blindly, both dangerous if the context has changed in the meantime. The number serves precisely to close discussions already closed — "it has already been decided, see decision such-and-such" — and to make visible, to anyone arriving later, the reason for what they see. This holds equally for a human team, where the log prevents re-litigating what had already been settled, and for a large language model.

There is in fact a second beneficiary of the log, besides whoever will read it in future: the large language model itself, during the work. Re-presenting at each step the decisions already made together with their rationale enriches the model's context and guides its reasoning, keeping it away from a well-documented failure mode in iterative work with a model — state revisitation: the model returns to solutions already explored and discarded without recognising the cycle, re-proposing them with minimal shifts and no real progress. The known cause is the lack of a structured memory of what has already been traversed: the model detects repetition only among recent steps and neglects the more distant ones, and the phenomenon is not merely lexical but semantic — the same conceptual territory re-crossed with different words. An explicit decision log, kept in context, is precisely the memory of already-visited states that the model lacks during the dialogue: it makes present and citable what has already been decided and discarded, and replaces an implicit, volatile trace with an explicit, persistent one. It is the same service the log renders to the human team — not re-deliberating what is closed — offered here to the machine.

The log is not immutable in the strict sense of the term. The method adopts the "living document" variant: a superseded decision is not deleted, it is updated in a tracked way, so that the history remains legible. Revising a choice in the light of new information is the health of the drafting process, not a failure to be hidden.

---

← 04 · The iterative dialogue and its open points · The Method · 06 · The specification's anchors →