Main idea

Each card of a product reference model carries a log where entries are added and previous ones are never corrected. An entry citing a code version signals that the product changed. An entry citing none signals something else: it is our understanding that changed, not the software.

The distinction looks minor at the moment of writing it. It is what makes it possible, six months later, to answer a question nobody knows how to handle otherwise: did we fix a card, or did the product evolve? Without it, the two movements blur into a single "last updated on".

The upkeep mechanism holds thanks to it: the reference version acts as a cursor and gives, with a single command, the list of what has moved in the product since the last update — hence the list of what remains to be recorded.

Why it matters

This separates two kinds of obsolescence that call for different actions. A card lagging behind the product is caught up mechanically, by rereading the sources of the new version. A card corrected because we had misunderstood calls for a question: what misled us, and has that cause gone away?

It also lets you judge the reliability of a description: a card whose log carries nothing but corrections of understanding was written too fast.

Nuances and limits

The mechanism assumes a citable product version — a repository, a release number. On a system with no clear versioned reference, the distinction becomes declarative and wears thin.

And an append-only log grows without limit: beyond a certain volume, you have to know what to do with it, which is a problem this note doesn't solve.

Open questions

• How often should the reference version be brought up to date, given that every postponement lengthens the list of what will have to be recorded in one go?