When the design doc and the code disagree, which one is wrong?

Development covered 5 Aug 2026 to 7 Aug 2026 (commit dates).

This project keeps a set of design documents that are meant to be the specification: what each system is and why. The game is a large amount of code written against those documents over months. This stretch was a reconciliation pass, and it turned up dozens of places where the two disagree.

The interesting question is not how to find them. It is what to do with each one, because the answer is genuinely different case by case.

Both directions were correct, in the same afternoon

Sometimes the document is right and the code drifted. A number was tuned in a hurry, a rule was implemented approximately, an exception crept in. Those are ordinary defects and the fix is in the code.

Sometimes the code is right and the document is stale. Implementation taught us something, a mechanic was replaced by a better one, an idea was tried and abandoned. There the document is the defect, and the fix is to rewrite it as though it had always said the new thing.

The trap is having a policy. If your rule is that the document always wins, you spend your time reverting improvements that were made for reasons nobody wrote down. If the code always wins, the specification degrades into a summary of whatever happened, which is worth nothing, because the reason to have a specification is to hold a position the code can be measured against.

So each disagreement gets argued individually, and I make myself write the reason. The useful question is which side knows something the other does not. Code that diverged because reality pushed back knows something. Code that diverged because somebody was moving fast does not.

The most expensive kind of stale

Two categories of drift caused far more trouble than the rest, and both are about the document making a claim about existence.

A document that describes a feature as built when it is not. Someone reads the specification, believes the thing is there, builds on top of it, and finds out much later. This wasted more of my time this stretch than any wrong number.

And a document naming something the project does not contain: a file that was renamed, a value that moved, a mechanism that never shipped under that name. The reader searches, finds nothing, and has to decide whether they are looking at a documentation error or their own misunderstanding. That decision costs twenty minutes every time.

The second one is checkable, so it is now checked. A test walks the specification set and fails when a name it uses in a technical sense does not resolve to something in the project. That check found six on its first run, and no other process in the project would ever have caught them, because prose is not compiled and no player is harmed.

Present tense, and no history

The rule that turned out to matter most is stylistic, which surprised me.

Documents are written strictly in the present tense, describing how the thing is, with no changelog and no narrative of how it got here. No previously this, now that. No note about a decision being revisited. If a value changed, the document simply states the new value as if it had never been anything else.

The reason is that these documents are read as the current specification by people, and increasingly by tools, who need one answer. A paragraph describing how the mechanic behaved in some earlier season is an invitation to implement that version, and once two versions are described in the same file, any reader has to guess which is live. Version history is what the repository is for.

The corollary I keep having to enforce on myself: when editing, replace the stale text rather than appending the correction. Appending feels safer and it produces a document that reads like an argument between three people.

Construction tickets are not documentation

Last piece of the same structure. This project also produces work orders, the step by step plan for a particular build, and those are deleted when the build lands.

That felt wasteful the first few times and it is the healthiest rule in the set. A plan describes an intention, and once the code exists, the code is the truth about what was done. A finished plan left lying around is a document that describes the present incorrectly and gets more wrong every week, and someone eventually follows it into conflict with the running system.

Two durable places to put things: the specification, for intent, and the code, for behaviour. Anything worth keeping from a plan gets promoted into one of those before the file goes. Everything else was scaffolding.

Try it in your browser: Cultivation Game.