How to Write a Decision Record for an AI That Affects People

Design for one test: could a colleague who was absent reconstruct the reason, the authority and the result from this record alone, without opening the full prompt or the customer's file? If not, add a reference. If it needs the entire raw input, redesign the workflow so the record can cite scoped, access-controlled evidence instead.

Two fields deserve more than a table row.

reason_code is the load-bearing field, and a controlled list is the only version that scales. A consumer-lending notice workflow illustrates the failure precisely: a code map turned model reason code R14 into the sample-form phrase "insufficient credit" while the model actually scored length of credit history, and by the time anyone noticed, the same drift had already reached hundreds of letters (Botminds on adverse action automation). When the code list, the code map, and the policy version move together and are stamped on the record, that class of error becomes a version comparison rather than an audit finding.

reviewer needs to capture the oversight mode, not just a name. Human in the loop means the person authorizes before execution; human on the loop means they monitor a population and intervene when patterns look wrong; over the loop means retrospective audit only (Databricks on human in the loop). Storing which mode applied, and the person's role, is what lets you argue later that the review was real rather than available.

A minimal shape:

{
  "decision_id": "d-01J8ZQ4K7",
  "occurred_at": "2026-10-14T09:12:03Z",
  "decision_class": "customer_credit_line_change",
  "subject_ref": "party:9f2c...",
  "system_version": "sha256:4b1e...",
  "policy_version": "credit-policy-7.2",
  "reason_code": "R14_LENGTH_OF_HISTORY",
  "reviewer": { "id": "emp-4471", "role": "credit_analyst", "mode": "human_in_the_loop" },
  "evidence": [{ "kind": "bureau_report", "ref": "bureau:77aa...", "sha256": "..." }],
  "outcome": "verified",
  "appeal": { "path": "portal/reconsideration", "deadline": "2026-11-13" }
}

Note what is not there: no chain of thought, no raw prompt, no copy of the bureau report. The record cites evidence and describes the decision. It does not archive reasoning traces, which are expensive, sensitive, and not a dependable audit artifact.

If you get one field right, make it this one.

A reason code is a stable identifier for one specific, defensible explanation of a decision. It is not a model feature name, not a score contribution, and not a sentence. It is the join key between the model's behavior, the policy's justification, and the letter or message the person receives.

The regulatory logic is concrete. Under Regulation B, a creditor generally must give an applicant a statement of specific reasons for adverse action (CFPB, 12 CFR 1002.9). Generic phrases fail that test. "Incomplete application" is acceptable only when the file truly lacked information the creditor needed to decide; if the file had enough to decide, the notice must list the actual reasons for denial (CrossCheck Compliance on adverse action notices). Specificity is a record-design problem before it is a writing problem.

So build the code list under three rules:

1. Every code maps to one plain-language sentence per audience (applicant, candidate, internal reviewer) and one internal justification.
2. Every code is versioned with the policy that authorizes it, and retired codes are retained so historical records stay interpretable.
3. Every code is testable: a unit test asserts that a given scored factor produced the expected code, so a model change that shifts meaning fails CI rather than shipping letters.

When that exists, the first question in an appeal ("why was I declined?") resolves to a template lookup keyed on reason_code plus policy_version. That is the boring answer you want.

Record the decision before the side effect, then append the outcome. This is the difference between a log and a ledger.

Here is the shape with verification built in:

async function decide(input: ApplicantInput) {
  const d = await evaluate(input);            // typed facts + deterministic policy
  const record = await decisions.insert({ ...d, outcome: "unknown" });

  if (d.verdict !== "allow") return record;    // hold, block, or route to review is still a decision

  const result = await core.applyChange({
    subject: input.subjectRef,
    expectedVersion: input.version,
    idempotencyKey: record.decision_id,
  });

  return decisions.appendOutcome(record.decision_id, {
    state: result.version === input.version + 1 ? "verified" : "unknown",
    resultRef: `core-event:${result.eventId}`,
  });
}

Three properties follow. A crash between insert and apply leaves a durable record with state unknown, so reconciliation can find it. A duplicate retry reuses the idempotency key, so the person is not double-charged or double-rejected. And a hold verdict is itself a recorded decision, which matters because regulators increasingly ask about the decisions that were stopped, not only the ones that went through.

For the review phase itself, make approval an appended event rather than an edit to the original record. The reviewer sees the task summary, evidence references they are entitled to open, policy reason codes, the expected change, and an expiry. Their approval is a new immutable entry that names them, their role, and the time. If the review times out, that is also an event. Silent escalation to auto-approval is the single most common way a "human in the loop" claim collapses under examination.

Under GDPR Article 22, a person has protections against decisions based solely on automated processing that produce legal effects or similarly significant effects, and where the exceptions apply, the controller must implement safeguards that include the right to obtain human intervention, express a point of view, and contest the decision (Article 22 GDPR). The ICO's guidance turns this into an operating checklist: give people information about the processing, provide simple ways to request human intervention or challenge a decision, and carry out regular checks that the system works as intended (ICO on automated decision-making).

That maps to four record fields that must be externally renderable: the reason code with its plain-language sentence, whether a human authorized the decision and in what mode, the appeal path, and the appeal deadline. Everything else (evidence digests, internal model versions, reviewer employee ID) stays internal.

Two design rules follow. First, the external view is a projection, not a copy: render it from the record at request time so it always reflects the policy version in force when the decision was made. Second, keep the appeal deadline in the record, not in a downstream ticketing system. If the notice clock and the record clock are separate, they will diverge, and you will discover the divergence in a complaint rather than a dashboard.

Retention is where most programs default to a single number and inherit a decade of unnecessary personal data. Derive it instead.

The general pattern in audit guidance is to retain records long enough to support after-the-fact investigation, with the specific duration left to organizational policy and applicable law; sector rules supply the floor. PCI DSS v4.0 requires at least 12 months of audit log retention with three months immediately available, HIPAA's security rule requires audit controls without fixing a period, and GDPR Article 30 requires records of processing activities, which can extend to AI decision logs where personal data is involved (Trussed on policy decision log retention). Where several regimes apply, keep the longest minimum.

Then layer the decision class on top:

Two retention obligations pull in opposite directions and must be reconciled explicitly. Privacy law pushes toward deletion (storage limitation, purpose tracking, and in the EU and UK the storage-limitation principle described in regional retention guidance (Scrut on data retention by region)). Audit and litigation obligations push toward keeping the structured record. The resolution is to delete the payload and keep the record. Evidence references expire with the underlying data; the decision row, reason code, policy version, reviewer and appeal state persist for the retention period.

There is a standards effort that takes this seriously. The Agent Audit Trail draft specifies hash-chained, tamper-evident records with pre-execution recording, deny reason codes, and tombstone-based deletion compatible with GDPR erasure requests, so the chain verifies even after personal data is removed (IETF Agent Audit Trail draft). You do not need to implement the whole draft to borrow the two ideas that matter: record before the action, and delete content while preserving proof.

Store the record in an append-only store, separate from the application database, with the decision-producing component as the authoritative writer. NIST's access-control architecture separates the policy decision point from the policy enforcement point, and decision-record guidance applies that split to AI systems by treating the component that produced the decision as the source of the log entry rather than the agent runtime (Trussed, citing NIST SP 800-162 and AU-3).

Concretely: write once, then append, with no updates to existing rows and only new outcome and review events. Hash-chain consecutive records so tampering is detectable, with periodic anchoring to an external timestamp so a rewritten chain cannot hide. Keep subjects and reviewers as opaque identifiers and join to identity in a system with its own access control. Apply least privilege by role so a reviewer sees the evidence, an appeals agent sees the reason code and policy version, and an auditor sees everything read-only. Encrypt at rest and in transit, and log access to the record store itself.

This is also where observability discipline pays off. Keeping task and trace identifiers on the record lets you join to the performance and latency data you already collect, without duplicating prompts or personal data into the decision store (Techlusion on agent observability).

A record you never read is a cost, not a control. Set a cadence by decision class, and make the review produce artifacts rather than impressions.

The one metric worth tracking above all others is the reversal rate by reason code. It tells you where the model and the explanation disagree, which is exactly where your organization will lose an appeal. A decision rule for what belongs in the record at all: log the moment the system crosses from interpretation into a consequential branch. That includes selecting a workflow, classifying a request into a risk tier, changing a record, sending a message, charging money, denying an action, escalating to a human, and declaring a task complete. Do not log retrieval chunks, retries, or draft sentences; those belong in traces, linked by ID.

A short sequence that avoids the most common rewrites:

1. List every decision class that affects a person, then rank by reversibility and regulatory exposure.
2. For the top class, write the controlled reason-code list with plain-language sentences before touching the schema.
3. Version the policy and the code list together; stamp both on the record.
4. Implement the two-phase write, with unknown as a first-class outcome.
5. Separate the internal record from the external projection, and put the appeal deadline in the record.
6. Set retention per class from the table above, with payload deletion and record persistence.
7. Stand up the weekly sample and the monthly override review before you scale volume.

If you are building this on top of several model providers, the plumbing is where effort hides. Quanta Inference exposes text, image, video, audio, and embedding models through one OpenAI-compatible API key, prepaid and priced in US dollars (https://quantaintelligence.ai/inference), which keeps the version stamps in your record pointing at a single integration rather than one per vendor.