Main idea

Updating a product artefact has always meant correcting its previous version: you reopen the specification written eighteen months ago, look for the paragraphs affected by the latest release, and rewrite them. The document then inherits everything that was not reread — behaviours removed since, screens that no longer exist, assumptions disproved during development.

The other route is to throw the previous version away and regenerate the artefact from the repository: the support documentation after a release, the changelog, the functional specification of the current state. The document no longer carries the build-up of its versions; it carries the date on which the code was read.

The gain is not writing speed. It is that the artefact stops being a stock to maintain and becomes a projection you rerun. A projection does not diverge: it is either out of date or redone.

The rule applies within a single document as soon as it mixes two kinds of content. In a product object card, the body describes reality as it is in the code: it can be thrown away and redone without losing anything. The gaps between that reality and what you would like, on the other hand, come from a human decision, cannot be found anywhere if you lose them, and therefore belong in a separate block that no regeneration touches. What you regenerate and what you maintain can only live together if they are visibly separated.

Layer added by "I wrote a product's ontology. Three times, I thought I was done." (2026-08-11).

Layer added by "Four days of vibe coding in the shoes of a rusty PM" (2026-07-28). The reversal does not only concern updating an existing document: it also affects the moment the first document is written. On an internal tool built directly by someone from product, there was no prior specification — the person dived in, built, showed it, received change requests and iterated. The behaviour emerged in the product, and the functional documentation was generated afterwards from the code. The usual sequence is then turned completely on its head: you do not regenerate a document because you failed to maintain it, you generate it because it was never written in the first place.

Why it matters

This is what makes the gap between the product and its documentation manageable without discipline. As long as you update, the divergence builds up with every skipped iteration; once you regenerate, a skipped iteration leaves no debt — the next regeneration starts from the same place.

It also changes what you archive: keeping the ability to regenerate becomes more useful than keeping the last version produced.

Nuances and limits

The code does not carry the intent. A regenerated specification says what the product does, not why that behaviour was chosen or what was set aside — and that loss is invisible, since the document looks complete.

Regeneration is not free either: it needs reviewing, and a wrong output that looks right costs more than a plainly out-of-date document.

Layer added by "Ontology-Driven Design: what if the ontology became the safety net for AI-generated code?" (2026-10-29). Rebuilding a business ontology from the code, rather than a specification, comes with a limit of its own: the result is a structured interpretation of the business derived from its implementation. An implicit rule can slip through the extraction, and a historical behaviour — a workaround, a leftover — can be mistaken for an intentional rule.

Open questions

• How do you notice that a regeneration has erased a human decision, when what it returns is a perfectly well-formed document?