Auditability when the model gives no written reason

An auditor asks two things about any automated decision: what did the system see, and what did it do. A third question, why did it do that, is the one people expect and the one a decision model cannot answer, because Jev "is not trained to generate text" [1]. This page is about what to keep so the first two questions have complete answers, and about the cases where the third question is required and the model has to hand off.

What a Jev answer contains

For a Choice question, the answer is the chosen option, a probability for every option, and a confidence number from 0 to 1 computed from how spread out those probabilities are; for three options the docs give the formula (3 times the largest probability, minus 1, divided by 2) [2]. For a Score question, the answer is a probability per level and a score that is each level number multiplied by its probability and added up, so it can land between levels; the docs' example is a score of 1.43 with confidence 0.35 from probabilities of 0.57 on level 1 and 0.43 on level 2 [3]. For a Noul, the answer is one probability from 0 to 1, with no separate confidence number [4].

That is everything the model says. It is numeric, it is complete, and it repeats closely on the same input and version: TypeSafe's batching cookbook reports a standard deviation of 0.0 across repeats for 11 of 13 questions [5], and LangChain measured a mean per-case variance of 0.0000149 across 100 repetitions on five cases [7]. A record of these numbers is a record of what the model actually did, with nothing added.

The seven fields of a complete record

Store all seven for every decision, escalated or not, and store them at the moment of the decision rather than reconstructing them later.

The state, as sent. The exact text or JSON the model received, because the model answers about that and nothing else. If the state was assembled from several sources, store the assembled version.

The questions, as sent. In their exact words, with the option list or the level descriptions. TypeSafe's jaggedness page says the model "answers the question you wrote, not the one you meant" [1], so the words are part of the decision.

Every probability returned, and the confidence number where one exists. Store all of them, including the options that were not chosen. The whole distribution is what lets an auditor see that a case was close, and it is what lets you measure drift later; measuring a decision model in production depends on it.

The threshold applied. The number the feature compared against, per action, at the time. Thresholds change, and a record that stores only the action loses the reason the action was taken.

The action taken. Routed, blocked, passed, escalated, fell back, and to what.

The model version. The version string, jev-1.13.0 at writing [6]. A version change is the most likely cause of a change in behaviour, and a record without the version cannot tell a model change from a data change.

The human label, if the case was escalated. Who decided, what they decided, and when. This is also the field that grows your labelled set on the hard cases.

Reveneau records the equivalent seven for every check its eval suite grades with Jev: the criterion, the state sent, the probabilities, the threshold, the verdict, the grader version, and the human label when a grade fell in the uncertain band and a person decided. A failed change can be traced to the grade that failed it. The suite runs ten times faster than it did with a language model grading it, on our own suite, and the record is the same shape it was before.

What the record cannot contain, and why that is sometimes better

The record cannot contain the model's reasoning, because there is none. A language model asked the same question would produce a paragraph, and that paragraph is generated text about the decision rather than the decision's cause. It can be fluent and wrong about what the model itself did. A probability distribution has no such failure mode: it is the decision itself. For an auditor who wants to know what the system did, seven numeric fields are a better answer than a paragraph. For an auditor who wants to know why, the reliable answer is the questions file, the threshold, and the labelled set: this is what we asked, this is the line we drew, and this is the evidence the line was drawn in the right place.

That reframing matters. The "why" of a decision-model feature lives in the specification and the calibration set, which are reviewed documents owned by people. Writing a specification for a decision-model feature is where that why gets written down.

When a written reason is required

Some decisions carry a rule that the person affected must be given a reason. Which decisions, in which sector, under which law, is a legal question, and we make no claim about it here. What we can say is what the feature has to do when the rule applies.

The decision layer hands off. Either a person makes the decision, with the model's probabilities as one input and their own written reason as the record, or a language model writes the reason from the same state the decision model saw, and the record stores which of the two wrote it and what they wrote. In the second case, the reason is generated text and should be labelled as such in the record, and the decision model's probabilities are kept beside it so the two can be compared. A reason that contradicts the probabilities is a signal the language model wrote an account that does not match the decision.

The specification states the hand-off per action, with the threshold at which it triggers. TypeSafe's own guidance to gate different actions at different confidence levels depending on their consequences [2] is the mechanism: the action that requires a reason is the one gated to a person.

Finding out whether the rule applies to you

Three of our guides cover how to find the rule for a sector without pretending to be counsel. The financial software compliance guide covers the regimes that govern lending, payments and advice. The healthcare software compliance guide covers patient data and clinical decisions. The regulated industry software guide covers the general method: name the regulator, find the rule, get a person with authority to sign off on the reading. None of them says which of your decisions needs a written reason. They say who does.

The pattern that holds across sectors is that the requirement attaches to the consequence and to the person affected, which is why it belongs in the threshold table of the specification and in the decision record's action field. A routing decision inside a support tool rarely carries it. A decision that denies someone something often does. Between those, ask.

What an auditor should be able to do with the record

Three things, and the record is complete if all three are possible without asking an engineer.

Reproduce a decision: take the stored state, the stored questions and the stored version, send them again, and get the same probabilities. That is what a standard deviation of 0.0 on repeats for 11 of 13 questions [5] points to, confirmed on your own cases, and it is a property a language model does not offer, because its wording changes between runs.

Trace a decision to its rule: read the stored threshold and the stored action, open the specification, and find the line that set that threshold for that action, with the labelled-set result that justified it.

Find the person: for any escalated decision, read who decided and what they wrote. For any automatic decision, read the version and the threshold and find the named person who approved that version against the calibration set.

If any of the three fails, the record is missing a field, and it is cheaper to add the field today than to explain its absence later.

The trade, stated plainly

A decision model gives you a complete numeric record of what it did and no account of why. A language model gives you an account of why that may not be true and a less complete record of what it did. For decisions where the why is set in a reviewed document and the what needs to be exact, the decision model is easier to audit. For decisions where a person is owed a reason, the model has to hand off, and the specification says where. The pillar guide has the rest of the governance sequence, why observability matters more with generated code covers the logging around the feature, and AI agent permissions and guardrails covers the case where the decision is inside an agent.

Keep the seven fields. Write the why in the specification. Hand off where a reason is owed. That is the whole of auditability for a model that does not write.