What must a decision-log row record when a risk model selects a tax return for audit?

## Why the row exists A risk model scores filed tax returns and selects some for audit. Months later two things can happen. One filer challenges their selection and asks on what basis it was made. Or an oversight review samples a year of selections and asks the same question of each, in bulk. Both are questions about a **past** decision, and the live system is a poor witness to it: the scorer has been retrained, the feature definitions have been revised, the upstream tables those definitions read have been refreshed, and the threshold has been retuned — often more than once. The record written at the time of the decision is what answers the question. Re-running the system today answers a different one, namely *what would we decide now*. That is the whole design constraint. Every field in the row is there because it is a value that existed at 09:21 on a Tuesday in March and no longer exists anywhere else. ## The fields, and what each one pins | field | what it pins | what breaks without it | |---|---|---| | `decisionId`, `decidedAt` | the identity and moment of one decision | an outcome that arrives later — an appeal, a closed audit — cannot be joined back to the decision that caused it | | subject reference (tokenised) | which filer the decision concerned | a challenge from one person cannot be matched to their record | | input snapshot | what the model was actually given | the decision can only be re-derived from data that has since moved | | model version | which scorer produced the score | the number is uninterpretable, and a discovered bug cannot be scoped to the decisions it affected | | feature-definition version | how inputs were turned into features | stored feature values are read under the wrong definition | | `score` | what the model returned | there is nothing to compare against the cut | | `threshold` and its policy version | the cut actually applied | a near-miss and a clear pass become indistinguishable under today's retuned cut | | action and deciding path | what the system did, and which path decided it | overrides and fallbacks are invisible and look like lost rows | ## The model version is the one people leave out The score without the version is a bare number. Suppose a reviewer sees `0.873` on a return selected last spring. Is that high? Only relative to the distribution that scorer produced, which is not the distribution the current scorer produces. Worse, when a defect is later found in one trained artifact — a feature read from a table that was empty for three days, say — the version stamp is what turns "we have a bug" into "these 4,100 decisions were made by the affected version and must be reviewed". Without it, the blast radius is the whole year. The same argument applies, less obviously, to the threshold. Thresholds are retuned far more often than models are retrained, and usually without producing a new artifact at all. A reviewer who reads the threshold from current configuration will silently misexplain last spring's decisions, showing a score of `0.84` as a comfortable pass when the cut in force that day was `0.86` and the return was selected by an override. ## Written on the decision path, not assembled afterwards The row is produced by the code that made the decision, at the moment it made it. A record assembled later by joining a request log, a feature table and a configuration snapshot is a reconstruction: it inherits whatever those sources look like now, and it has no way to represent the case where the model was consulted and then ignored. That last case matters more than it sounds. Decisions taken by a manual override, by a rules layer, or by a fallback path when the scorer was unavailable still get rows — with the deciding path named, and with the model's score included if one was produced and set aside. Otherwise a reviewer sampling a year of selections sees gaps and cannot tell a decision the model never made from a record that was lost. ## What belongs in a different record - **Why the score was what it was** — attributions, per-decision explanations, reason codes — is a separate body of work with its own record; the decision row holds inputs and outputs, not causes. - **The serving tier's access log** answers who called what and how fast. It is not the decision log and does not carry the score, the version or the cut. - **The training-run record** answers how the artifact was built. The decision row references the artifact's version; it does not restate its provenance. A good answer names the fields, explains why each is unrecoverable later, and does not try to make one record do all four jobs.