Main idea

Updating a product artifact has always consisted in 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 — behaviors removed since, screens that no longer exist, assumptions disproved by development.

The other route consists in throwing the previous version away and regenerating the artifact from the repository: the support documentation after a release, the changelog, the functional specification of the current state. The document no longer carries the accumulation of its versions, it carries a date at which the code was read.

The gain is not writing speed. It is that the artifact 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 inside a single document as soon as it mixes two kinds of material. 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 want, for their part, 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 coexist on condition of being 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 as a Rusty PM" (2026-07-28). The reversal does not only concern the updating of an existing document: it also touches the moment the first document is written. On an internal tool built directly by a product profile, there was no prior specification — the person dove in, built, showed it, received change requests and iterated. The behavior emerged in the product, and the functional documentation was generated afterwards from the code. The usual sequence then flips completely: you do not regenerate a document because you failed to maintain it, you generate it because it was never written before.

Why it matters

This is what makes the gap between the product and its documentation workable without discipline. As long as you update, the divergence accumulates with every skipped iteration; as soon as 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 behavior was chosen nor what was set aside — and that loss is invisible, since the document looks complete.

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

Open questions

• What share of an artifact must stay handwritten because no regeneration can recover it?