liveBook · Manning

Decision record

As explained in Designing AI Agents

An inspectable record of a decision or conclusion and its supporting evidence, assumptions, and rationale.

A decision record makes a conclusion inspectable by connecting it to evidence, assumptions, uncertainty, and a reason for stopping or continuing. It can also identify the next route: proceed, gather evidence, choose another approach, or escalate to a person. Source and timing information help distinguish current observations from assumptions or stale summaries. section 5.1 section 5.1.1

A generated rationale is a claim about a decision, not proof of the model’s internal reasoning. An action-and-evidence trace records what the harness observed and did, but does not by itself show why those observations support a conclusion. Retain both, together with represented inputs, model configuration, tool results, tests, and state transitions. section 5.1.1 section 5.2.2

Table 5.1 Three artifacts often confused with reasoning
Artifact
 
Owner
 
What it records
 
Useful for
 
What it cannot prove
 
Private model reasoning
Model runtime or provider
Provider-controlled deliberation or summary
Improving the response and diagnosing a run
The exact causal basis of the decision or an audit proof
Decision record
Application or harness
Claims, evidence references, uncertainty, route, and stopping reason
Reviewing dependencies and governing the next step
That the proposed action occurred or succeeded
Action-and-evidence trace
Harness, tools, and environment
Reads, calls, results, tests, and state transitions
Reconstructing what happened and checking external evidence
The model's private reasoning or that a conclusion follows from the trace

Compare the ownership, uses, and evidentiary limits of private reasoning, decision records, and action-and-evidence traces. section 5.1.1

A coding change

Read the target function and contract, then search callers, tests, and interfaces. Record the selected change, assumptions, and unresolved dependencies separately from the reads, edits, commands, and actual test results. The record explains the choice; the trace shows what happened. section 5.2.2

A budget decision

For a 100-yuan cap, a record can retain a host-owned snapshot showing 60 yuan confirmed and zero reserved, a proposed 50 yuan, the 110-yuan projection, and the cap rule. The policy denies the proposal. The record supports review, but the runtime gate must enforce the limit and reserve amounts atomically before execution. section 9.6

An architecture decision ledger extends the record across revisions. Link a versioned selection card, baseline and candidate trials, evaluation receipt, and deployment. When operating evidence changes an assumption, preserve the old card and receipt, issue a new version, and link the reason for keeping, repairing, recomposing, simplifying, or retiring the decision. section 11.8 section 11.1.2

How Designing AI Agents covers it

How deep it goes
Specifies decision contents, evidentiary limits, and versioned ledger practices, with concrete production examples.
Examples
Uses a coding change, a compensation-cap denial, and an architecture revision triggered by concurrent editors.
What you can do after
Apply decision records to link claims and evidence, review proposed actions, and preserve the reasons for architecture revisions.
How it connects
Connects decision records to action-and-evidence traces, governance, state provenance, and architecture decision records.

Also explained in

Compare how 2 books explain decision record →

Related concepts

This explainer was generated by Manning's knowledge graph from the text of Designing AI Agents. The section links point to the parts of the book it draws on.