§1 · Premise
Capture the why before it disappears
Write down why you built the wall, or the next machine will build a door through it.
An Operational Decision Record (ODR) is a short, immutable note that captures one operational call and the reason for it, stored where the next operator will look. It is the operational sibling of the Architecture Decision Record: same DNA, different surface. The ADR records a decision about how a system is built; the ODR records a decision about how a system is run — a patch deferral, a failover, an alert-threshold change, a recovery-time target, a scope cap under pressure.
It is not a runbook (which says how to do a recurring task), not a ticket (which tracks work), and not a postmortem (which explains a failure after the fact). An ODR is written at the moment of the choice, before the outcome is known — and if it takes more than about ten minutes, the format is wrong. It is also not documentation theater: a record that reads as a sales pitch for a decision already made, with no cost listed, has failed.
AI made operational output cheap. It did not make the reasoning behind that output cheap, and it did not make it durable. When a human or an agent makes an operational call, the system changes in seconds and the reason evaporates just as fast. Six weeks later an engineer doing root-cause work is no longer engineering — they are doing archaeology, guessing the intent of a person who left or an agent that remembers nothing. The ODR is the cheapest known instrument to stop that. The AgODR extends the same discipline to autonomous agents, forcing them to record the reasoning before they act — which, as a side effect, makes the agent's decision measurably better.
§2 · Falsification bet
The bet we are willing to lose
Every CTRL ALT PRESS piece states a claim you can prove wrong. The trust layer is a falsifiable claim with a horizon and a check, not a testimonial.
Position ODRs add durable reasoning, not ceremony Horizon Two quarters after adoption Checkable Root-cause time, “why is it like this?” questions, and agent-change reason coverage — measured
If a team adopts ODRs and AgODRs with a real operating model — a height bar, a review owner, repo-adjacent storage, an agent template that writes before it acts — and after two quarters their root-cause time has not dropped, their “why is it like this?” questions have not dropped, and not one agent-made operational change carries a captured reason, then the practice added ceremony without function and I was wrong. I would want the data, because the WIRE evidence says the opposite. Hold every exercise to that bet: a record that reads as a sales pitch for a choice already made, with no cost listed, has failed.
OPEN · CHECKABLE Root-cause time, “why is it like this?” questions, and agent-change reason coverage — measured
§3 · Why now
The debt you cannot see on your balance sheet
As AI speeds up production, the debt inside people and artifacts becomes a far larger risk than the debt inside the code. The Triple Debt Model (Storey, 2026) splits software health into three eroding layers. The deeper root is older: Naur's Programming as Theory Building (1985) — the real system is a theory living in the heads of the people who built it, and the code is a lossy translation. Agents build enormous operational change while forming no theory at all; the unrecorded reasoning behind a machine's change is the Decision Shadow, and the shadows accumulate into systems nobody understands.
- 01
Technical debt
Lives in the thing itself — messy code, a fragile network path.
Operates on Highly visible; tools can scan for it. The smallest of the three risks once AI accelerates production. - 02
Cognitive debt
Lives in people — the quiet erosion of shared understanding.
Operates on “Cognitive surrender”: uncritically accepting machine reasoning because it looks correct. When an agent generates the config, the human never builds the mental model that writing it would have forced. - 03
Intent debt
Lives in the artifacts — the complete absence of externalized reasoning.
Operates on Nobody captured why, so the reason is permanently gone. This is the debt ODRs and AgODRs are built to pay down.
Where it lands This debt lands, unpriced, on the Strategist's balance sheet as key-person risk, stalled due diligence, repeating incidents, and slow onboarding. The ODR/AgODR habit is how you start paying it down before it compounds.
§4 · The taxonomy
One habit, four records
Every record answers the same question — what did we decide, and why — but the surface and the author differ. The whole field is one 2×2: architecture versus operational, human author versus agent author. “Operational” already says it is not architecture, so the operational records carry the O. The four together give an organization one decision substrate across humans and machines, build-time and run-time. The ADR (Nygard) is a durable architectural fact, immutable once accepted; the ODR keeps that DNA and adds one structural section — REVIEW — because an operational decision is a time-bound risk acceptance, not a permanent fact.
| Author | Architecture — how it's built | Operational — how it's run |
|---|---|---|
| Human | ADR — Architecture Decision Record | ODR — Operational Decision Record |
| Agent | AgDR — Agent Decision Record (writes before it codes) | AgODR — Agent Operational Decision Record (writes before it acts) |
§5 · Who gets what
Where the value lands by archetype
One habit, but its center of gravity shifts with where you operate. Pick your stance to see the operational mental model and the tier where the value lands.
Supporter L1–L2
Builder L3
Architect Principal
Orchestrator EM / Director
Strategist CISO / CTO / VP
§6 · Curriculum
Three modules, then the capstone
Each module is one move: an objective, the core idea, an exercise you do on paper, and a checkpoint that names the failure mode. Module 1 is the gate — leave it writing CONSEQUENCES with only upside and every later record is a pitch.
Objective
Write a defensible ODR in under ten minutes, and understand why REVIEW is the field that makes it survive an audit.
The five sections
- STATUS — closed vocabulary: proposed | accepted | deprecated | superseded. Only proposed is freely edited; once accepted, the record is immutable.
- CONTEXT — the situation that forced the choice, in plain operational language: the constraint, the freeze, the deadline, the blast radius.
- DECISION — the call itself and any compensating control. The actual action taken, not “we looked into it.”
- CONSEQUENCES — the trade-offs, both directions. Upside only is a sales pitch and gets rejected. Name the cost you are accepting and who signed off.
- REVIEW — when does this decision get re-tested? A date and a trigger condition, whichever comes first.
Why REVIEW is load-bearing
An architecture decision is a fact until superseded; an operational decision is a standing risk acceptance until re-tested. A risk acceptance with no expiry is a permanent hole nobody owns. REVIEW converts “we decided this once” into “we decided this until a named date or a named trigger” — the difference between a decision you can defend in an audit and one you get cornered on.
The three formats
Scale up only when forced: the Y-statement (one sentence, ~90 sec — the default for agents), Nygard (~1 page — the standard default), MADR (2–4 pages — regulated or large irreversible calls). The Y-statement template: In the context of [situation], facing [problem], we chose [option] and rejected [alternatives], to get [benefit], accepting [cost]. If you cannot fill the cost blank, you are not ready to make the change. That friction is the feature.
Exercise 1.1
Take one real operational risk acceptance from the last month (or the supplied DB-failover scenario), fill all five sections, and make REVIEW carry a date and a trigger. Trade with a partner whose only jobs are to find the consequence you left out and the loophole that lets your risk acceptance live forever.
Checkpoint
If CONSEQUENCES lists only upside, you wrote a pitch. If REVIEW has a date but no trigger (or a trigger but no date), it is half a control. Both, or it does not pass.
Objective
Decide when a call earns a record, store it where it survives, and run the lifecycle so the chain stays trustworthy.
The height bar
- Incident command — a failover, vendor page, rollback, or regional cutover made under pressure before root cause is known.
- Business continuity — an RTO/RPO target and the cost trade-off behind it (“4 hours, not 1, because hot standby doubles infra cost”).
- Appetite enforcement — a scope cap and the feature you cut to hold a deadline, with the sponsor's sign-off and date.
- Risk acceptance — a patch deferral, a threshold raise, a temporary mitigation standing in for a real fix.
- The Architect's “and not”: the path you deliberately did not take, recorded so nobody reopens a contained failure mode.
The storage rule
The single most-repeated finding: store ODRs where the team already works — the repo, the runbook, the change-management system — never in a disconnected wiki. A record nobody can find at the moment of decision is worthless. This one rule beats all format choices.
The lifecycle
proposed → accepted → deprecated → superseded. Only proposed is editable; once accepted, the record is immutable — if the decision changes you write a new ODR that supersedes the old one, with explicit supersedes / superseded_by links. The true state of the system is the whole chain over time, not the latest note. Quiet edits break the audit trail.
Exercise 2.1
Draft three things for your environment: the one-line rule that decides when a call needs an ODR; the exact location ODRs will live (name the repo/system); and the mandatory checkpoint in your change process that links the record (a PR-template checkbox, a change-ticket field).
Checkpoint
If your storage answer is “a Confluence space” or “a shared drive,” you have chosen the single biggest killer of the practice. Move it adjacent to the work.
Objective
Design a record that forces an autonomous agent to externalize its operational reasoning before it acts, with a human-checkpoint gate sized to blast radius — closing the Decision Shadow at machine speed.
Why agents need their own record
Agents make operational calls in seconds — restart a service, scale a fleet, raise a threshold, fail traffic off a degraded node — with no memory across sessions and no one asking why that action over three valid alternatives. The fix mirrors the AgDR from build-time: the agent writes the record before it acts. That is not bureaucracy bolted on — it is a reasoning scaffold that measurably improves the action it then takes.
The AgODR fields (ODR + agent)
- Y-statement — the whole decision in one line (the non-negotiable opening).
- Options table — the alternatives considered, rejected options carrying equal weight; this is where the scaffold value lives.
- Provenance — which agent, which model, which session, which triggering signal.
- Autonomy level & confidence — did it act or recommend, how confident, against what threshold.
- Verification — a named check against ground truth, not “it looked fine.”
- Reversibility / rollback — the exact path back; an agent's action must be undoable.
- Human checkpoint — whether a human must approve before commit, sized to blast radius.
- REVIEW — a re-test the agent itself can be scheduled to perform, closing the loop without a human remembering.
The blast-radius gate
- Reversible, low blast radius (restart a stateless pod): agent acts, emits AgODR, no checkpoint.
- Reversible, high blast radius (regional failover): agent emits AgODR, acts, human notified for immediate review.
- Irreversible or risk-accepting (defer a patch, raise a threshold past policy): agent emits AgODR in proposed and blocks on human approval before commit.
Exercise 3.1
Specify the AgODR fields you require beyond the five ODR sections; your three-tier human-checkpoint gate mapped to your own actions (one example per tier); and the confidence threshold above which an agent may act autonomously, and who set it.
Checkpoint
A human checkpoint on everything trains rubber-stamping; one on nothing lets an irreversible agent action commit unreviewed. The gate must discriminate by blast radius.
Brief
Design the operating model that makes ODRs and AgODRs stick in your own organization (or the supplied scenario), then defend it before a panel in the CTRL ALT PRESS voice — the Operator, the Architect, the Strategist, and the Editorial Voice.
Scenario
A regulated enterprise runs an autonomous ops-agent that already takes low-risk remediations and recommends higher-risk ones. Engineers spend hours per incident on “why is it like this” archaeology. An auditor has asked, in writing, “how do you control what your AI changed?” You have 60 days, no new headcount, and you may not stop the agent.
Must contain
- The ODR five-section template and the AgODR template, with your required agent fields.
- The height bar and the repo-adjacent storage location.
- The three-tier human-checkpoint gate and the autonomy confidence threshold, with who owns it.
- The lifecycle and supersession rules, plus the review owner and cadence — the answer to “records without a review habit rot.”
- The auditor's answer: the exact decision-trail artifact you would hand them, and what share of agent changes it covers.
- The bleed-rate metrics you will be held to at 60 days — no invented ROI multiple.
Scoring
Scored 0–5 across six dimensions: ODR craft, height bar, AgODR design, operating model, audit answer, and honesty. Pass ≥ 18/30; distinction ≥ 24 with no dimension below 3.
You will leave able to
- Write an ODR in under ten minutes using the five-section structure, with a REVIEW field that carries both a date and a trigger condition.
- Apply a height bar that reserves records for hard-to-reverse operational calls and keeps trivia out.
- Design an AgODR template that forces an agent to record reasoning before acting, with a human-checkpoint gate sized to the action's blast radius.
- Stand up the operating model — storage, lifecycle, review owner — that survives past month two, defended against the seven known failure modes.
- Frame the value honestly as a bleed rate and cheap insurance, with no invented ROI multiple to be discredited.
§7 · Inoculation
The seven ways it dies
Almost every team adopts decision records; almost none keep them two years. Konishi's seven failure modes, each with its counter. The common root cause of all seven: the team adopted the format but not the operating model — they never defined when a record is required, who reviews it, where it lives, and who owns the habit.
| Failure mode | What it looks like | The counter |
|---|---|---|
| Early momentum death | The first five records are the only five | A mandatory PR / change-template checkbox |
| Skipping load-bearing walls | Trivia recorded, big risky calls skipped | The height bar from Module 2 |
| Sales pitches | All upside, no cost listed | Reviewers reject any record without negative consequences |
| Quiet edits | Accepted records edited later | Immutability — supersede, never edit |
| Buried storage | Records in a wiki nobody opens | Repo-adjacent storage (the biggest killer) |
| Decision drift | The change ships, the record never gets written | Record creation is a required checkpoint; for agents, write-before-act enforces it |
| Single owner | One enthusiast writes them all, then leaves | Distribute by pair-writing the first records |
§8 · Evidence floor
The evidence, and the honesty rule
One substantial long-run case study carries real numbers — the IBM Watson WIRE team. The honesty rule sits beside it: do not invent a precise ROI multiple the research does not support; frame the value as a bleed rate and cheap insurance. Claims carry their provenance; vendor and unverified figures are labeled.
- 01
Record density predicted system health — the two or three services causing 90%+ of daily problems had only one or two records, while comparable healthy services had about a dozen.
- 02
A known risk captured in a record still caused an incident nine months later because nobody re-read it.
- 03
The real system is a theory in the heads of the people who built it; the code is a lossy translation. When the team holding the theory dissolves, the system dies.
- 04
Software health erodes across three layers: technical, cognitive, and intent debt.
- 05
ADR format — Title, Status, Context, Decision, Consequences; immutable once accepted.
- 06
Agents form no theory and accrue a Decision Shadow; the fix is write-before-act, which doubles as a reasoning scaffold.
- 07
Seven recurring failure modes kill decision-record practices; three record formats scale with the decision's weight.
- 08
Frame value as a bleed rate and cheap insurance — no invented ROI multiple.
§9 · Enroll
Choose your delivery tier
Three modalities, same curriculum. Efficacy rises with the live, paper-first drills and the adversarial capstone defense — the in-person intensive is what justifies the premium and pairs with the agent-governance audit.
| Modality | Format | Efficacy | Positioning |
|---|---|---|---|
| Self-paced | 6 modules, the ODR/AgODR template pack, async record reviews | Entry tier — the template pack is the take-home value | The submittable exercises (1.1–3.1) carry the discipline |
| Virtual cohort | 6 weekly live sessions, paper-first drills, async capstone panel | High — the panel defense justifies the tier | Premium; capped to keep the drills honest |
| In-person intensive | Full workshop + live adversarial capstone defense | Maximum — the defense is embodied | Top tier; pairs with the agent-governance audit |
Completes the CTRL ALT PRESS premium catalog with The Triad of Prompt Lenses and The Experience Outcome Layer.