Capture Milestone Dates

Nothing in the previous two chapters produces a duration. Dates do, and they are the part of a specification most likely to be assumed rather than written down.

A milestone date is the atom of process reporting. How long did it take, how many reached this point, what share moved on, when did it stall: all of those are arithmetic on dates. If the date is not there, none of the arithmetic is possible, and worse, most of it will silently produce an answer anyway.

The capture rule is the metric

A date field does not record when something happened. It records when something was logged in the specific way that the thing which stamps the date was watching for.

Consider a real design. A date gets stamped by a rule that fires when an activity is saved with a particular type, a particular relationship to the record, and a particular pattern in its subject line. That is a perfectly reasonable implementation. And it means an activity logged through a different channel, or without the related record attached, or with a subject that does not match, stamps nothing at all.

The date never appears. Every metric built on it is then computed as though the activity never happened. So a person who did the work and logged it slightly differently is, in the number, identical to a person who did nothing. Nobody can tell them apart. Nothing errors.

Which is why the capture rule belongs in the specification, next to the date, written in a sentence a non-engineer can check: this date appears when X happens, recorded in way Y. Recorded any other way, it does not appear. If that sentence is uncomfortable to write, the report built on it should be uncomfortable to trust.

Backfill may only move a value in the safe direction

Once you know a date can go missing, the instinct is to backfill it from somewhere else, and that instinct is correct. A well-designed version refreshes a date nightly from an independent record of the same event.

The rule that makes it safe is one line: it only ever moves the value in the direction that cannot destroy information. If a hand-entered date is more accurate than the automated one, the backfill must not overwrite it. In practice that usually means the job only moves a date earlier, or only later, never both, and the specification says which.

A backfill without that rule will eventually replace somebody's careful correction with a worse automated guess, and nobody will notice for months.

Metrics with teeth need a higher standard

Some metrics only get looked at. Others trigger something: a record below a threshold gets swept into an automated action, a queue gets built from a filter, a person gets alerted.

For the second kind, a capture gap is not a reporting inconvenience. It is a process taking real action against records on the basis of activity it could not see. Say in the specification which metrics have teeth, because those are the ones whose capture rules have to be airtight and whose blind spots have to be published.