Preserve Decisions and History

The value of this chapter is almost entirely deferred. Nothing here helps this week. It decides which questions are answerable in a year.

Replaced and appended are both correct, for different things

A working system usually needs both, and the mistake is not choosing wrong. The mistake is not noticing there was a choice.

Replaced is right for current state: the system's present assessment, the latest rationale, the value as of now. There is one, it is the answer, and keeping every prior version clutters everything that reads it.

Appended is right for anything you might later want to ask a question about over time. What the score was in March. How often the assessment changed. Whether it moved after the meeting or before.

A well-built example does both, deliberately, and documents which is which: the current rationale is overwritten on every run, and the history log never loses what came before. Users are told explicitly which one to trust for “what did we think in March”, because otherwise they would reasonably read the current rationale and believe it had always said that.

Numbers and narrative in separate panes

One pane holds the sequence of numbers, which is what you scan when you want to see movement. The other holds the reasoning and whatever the human wrote at the time, which is what you read when something moved and you want to know why. Merged into one stream, both get harder to use and the numbers stop being scannable.

Write the full state, mark what moved

A history entry recording only what changed is compact and nearly useless six months later, because reconstructing the full state at a point in time means replaying every prior entry and hoping none were dropped.

Write every component every time. Then mark the ones that moved. Now a single entry is self-contained and change is still obvious at a glance.

Tag every entry with its trigger

Three things can produce a history entry: a person doing it deliberately, a side effect of an edit, and a scheduled job. Those mean completely different things. A considered human revision and a nightly recomputation that happened to land on the same value are not the same event, and a year later you cannot tell them apart unless the entry says which it was. One line per entry. It costs nothing at write time and it is unrecoverable afterwards.

The measurement you get for free

If your history preserves both what a person decided and what the system recommended, on every entry, then later you can ask: how often did they disagree? In which direction? Did that change over time? Is disagreement concentrated in one segment?

That is one of the most valuable measurements available about an automated system, and it is the subject of a whole chapter in the last guide of this pillar. You cannot compute it retrospectively. You either stored both sides from the beginning or that question is permanently unanswerable. This is the clearest example in the curriculum of a cheap storage decision buying an expensive capability later.