Library · Data Practice OS

Decision records and provenance

Reference guide · Published · Source reviewed 2026-11-06

Short answer. Every decision made with system or AI support writes a Decision record: what was decided, on which facts, by which rule version, from which context sources, under whose authority, reviewed by whom, and later what happened. It is Decision provenance made concrete, and it is the bottom layer of learning in the From data to decisions - the decision stack. The copyable schema is Decision record schema.

Status. Proposed practice, extending the decision provenance section of the AI readiness assessment (proposed). Not an agreed decision. Retention periods and privacy treatment must be confirmed with the organisation records management and privacy.

Why record decisions, not just data

Lineage tells you where a table came from. It does not tell you why this licence was refused on this day. Without a decision record you cannot:

answer an appeal, a complaint or a right-to-information request with the reasons as they were;
replay a decision under the rule version that applied (Effective dating);
tell whether an AI recommendation was followed, overridden or ignored;
measure outcomes, because there is nothing to link the outcome to (Outcome feedback loops).

What to record

Field group	Contents	Why
Identity	Decision id, decision type (from the Decision inventory), subject reference, timestamp	Find it and group it
Facts used	References to the source records, with their version or as-at time, not copies	Replay without hoarding personal data
Rule version	Rule card or decision table id, version, `effective_from`, matched row or path	"Which rule applied" (Rule authority)
Context sources	Documents, knowledge items and retrieval results the assistant used, with version	What the AI saw
AI involvement	Mode (read / recommend / approve / execute), model and prompt version, the recommendation, confidence	Separate the AI's contribution from the human's
Authority	Who made the decision, under which delegation	Accountability
Human review	Reviewer, action (accepted, changed, overridden), reason code, time taken	Human in the loop as evidence, not as a claim
Result	The decision and any reasons given to the customer	What was communicated
Outcome (added later)	What happened: appeal, reversal, repeat defect, complaint, none	Learning (Outcome feedback loops)

Record references, not payloads. Point to the source record and its version. Copy content only where the source may change or disappear and the decision cannot be explained without it.

W3C PROV as the shape

W3C PROV (overview) gives a vocabulary that fits decision records well:

Entities: the licence record (version 14), the rule card (v2026-07), the retrieved procedure document, the recommendation, the decision.
Activities: the retrieval, the rule evaluation, the model call, the officer's review.
Agents: the AI service, the officer, the delegation they act under.
Relations: the decision wasGeneratedBy the review, which used the recommendation, which wasDerivedFrom the licence record and the rule card. The officer actedOnBehalfOf the organisation.

You do not need an RDF store. Use PROV's terms as column and field names in an ordinary table or event, so the records can be exported as PROV if a regulator or partner ever asks. Pipeline lineage (OpenLineage) covers the data side; the decision record covers the decision side and links to it.

Where it lives

Write the record as an event at the moment of decision, from the workflow or application that holds authority. Do not reconstruct it later from logs.
Land the events into the platform as a governed data product, with a contract (Data contracts), classification and masking like any other product.
Make the record append-only. A correction is a new record that supersedes the old one, with a reason.
A decision record's rules_applied[] cites a rule id. Build-time provenance (which code implements that rule, and what proves it) is the audit chain in Tracing rules from legacy code to modern code.

Retention

In government, a decision record is a public record; in an enterprise it is usually a business record. Retention follows the applicable records authority's retention and disposal schedule that applies to the business function, not a platform default. Check the applicable schedule with records management (verify; for a worked government example, see Queensland Government recordkeeping guidance). Set the retention per decision type in the Decision inventory, and implement it as policy in the platform, not as a manual purge.

Privacy

Decision records about people contain personal information. Treat them as at least as sensitive as the source records they reference (Personal information).
Keep personal content out of the record where a reference will do. Mask free text such as reviewer notes for analytical use.
Model prompts and retrieved passages can contain personal information. Store them only when needed for explanation or evaluation, under a shorter retention where the schedule allows.
A new decision-record product about people needs a Privacy impact assessment.

Not when

Do not record every read-only query as a decision. Record decisions with a consequence: an approval, refusal, priority, payment or action.
Do not build a separate provenance platform first. A well-designed event table is enough to start.
Do not copy whole source records into the decision record "just in case". That creates a second, unmanaged copy of personal data.

Source links: Data Practice reading list.