What must a rules-plus-model decision layer record so a support agent can explain a denied refund months later?

## Two audiences, one record When a customer disputes a denied refund weeks later, two different people need something from the same event. The **support agent or case reviewer** needs to decide whether the decision was right: they want the specific rule, its version, the score band and the input values the layer saw. The **customer** gets a deliberately coarser sentence - both because the exact condition is not useful to them and because naming the precise constant that fired tells anyone probing the system exactly what to stay under. One record serves both, because the coarse wording is derived from the reason codes rather than stored separately. ## What the record holds - **Identifiers** - a decision id, the account, the request, and the timestamp the decision was emitted. - **The emitted action** - allow, challenge, decline, route to human case review - and which branch resolved it: a rule, the model's band, or the default. - **The rule side** - the rule-set version, and for every rule that matched: its id, its version, the action it proposed and its precedence. - **The model side** - the model version and the score or its band, recorded even when a rule won the resolution, because 'the rule declined a request the score thought was fine' is the most useful thing a reviewer can learn. - **The inputs that mattered** - the handful of values the conditions read: account age, redemptions in the last 30 days, refunds requested, linked-device count. A reviewer cannot judge a decision from the verdict alone. - **Reason codes** - a short list from a fixed vocabulary. ## Reason codes are a vocabulary, not free text If every rule author writes their own sentence, the reason field becomes prose that cannot be counted, translated, or mapped to a customer message. A curated code set fixes that: | Property | What it buys | |---|---| | Fixed and enumerated | Decisions can be counted by reason, so a spike in one is visible | | Mapped to wording separately | Customer phrasing and agent phrasing change without a decision-logic change | | Coarser than the rule id | The exact condition stays internal while the reason is still true | | Many-to-one from rules | Several rules can share a code, and the record keeps the rule id anyway | ## Why a blended score resists explanation A matched rule is self-explaining: it is a named condition with a version, and saying it fired is a complete account of why. A score is not. It is a function of many inputs at once, and the honest statement is 'this request landed in the high band', optionally with the inputs that contributed most. That is an explanation of a *kind*, not of a *case*. The consequence shows up in design: where a decision must be explained in specific terms, carry it with a rule rather than with a band. This is one of the quieter reasons the rules layer survives after a model is added - not accuracy, but attributability. And when rule contributions and the model score are fused into a single number, even the rule's own attributability is blurred, which is an argument for keeping the rule's hit in the record separately from the fused score. ## Write it at decision time, not later The tempting shortcut is to store only the action and reconstruct the rest by re-running the rules when somebody asks. It does not work, for three independent reasons: 1. **The rule set has moved.** Rules were edited, retired, re-ranked. Re-running today answers 'what would we decide now', which is a different question from 'why was this refund denied on the 3rd'. 2. **The model version has moved.** The score that decided is not the score a current model produces on the same inputs. 3. **The inputs are gone.** Velocity counters are time-dependent by construction; their value at that instant is not recoverable from today's aggregates, and a value reconstructed from a later state is simply a different number. Two practices make the record trustworthy. Give the rule set a **version identifier derived from its content** - a content hash over the published rule text - so a record can never point at a rule-set version that was quietly edited underneath it. And write the record on the decision path itself, as part of emitting the action, rather than assembling it from separate log lines afterwards, so a decision can never exist without its explanation.