Architecture or Process Decision Record¶
Decision record — instantiates Technical Debt Containment
A short, durable record written at the moment a shortcut is taken — naming why it was chosen and what future obligation it creates — so a legitimate expedient never becomes an unexplained, invisible dependency.
Most dangerous debt is not the shortcut that was obviously wrong; it is the reasonable shortcut whose reasoning evaporated. Architecture or Process Decision Record is the point-of-decision artifact that captures, right when an expedient choice is made, three things: why the normal path was bypassed, what future obligation the shortcut creates, and under what conditions it should be revisited. Its defining move is fixing the rationale and the obligation in writing at the moment of choice, before either fades — drawing the boundary that says "this is a deliberate, bounded piece of debt, not just how things are." It is not the aggregate inventory and not a scoring scheme; it is a single, durable narrative for a single decision, and the corpus of such records becomes the memory a system learns from.
Example¶
A regulatory agency, facing a natural disaster, grants a temporary emergency exemption that lets applicants bypass the normal multi-week permitting review to rebuild quickly. That expedient is entirely defensible — but left unrecorded, it is exactly the kind of shortcut that quietly becomes permanent practice, until years later no one remembers it was ever meant to be temporary. So staff file a decision record: the context (a declared emergency), the decision (fast-track path X), the obligation it creates (return to standard review by a named date; audit the fast-tracked approvals for defects), and the trigger to revisit (emergency lifted, or defect rate exceeds a threshold). Two years on, when someone asks "why do we still fast-track these permits?", the record answers — the shortcut is legible, and the obligation attached to it was named at birth rather than discovered in an audit. When the agency later reviews which emergency measures caused downstream problems, the records are what it reads.
How it works¶
The record is deliberately lightweight — a short template with context, decision, consequences, and a revisit trigger — filed at decision time and kept durably and indexed, so it can be found later by anyone tracing why the system is shaped as it is. The discipline that makes it a debt mechanism rather than mere documentation is that it must always name the obligation: not just "we chose X" but "X owes a future repayment of Y, revisited under condition Z." Over time the accumulated records feed the postmortem loop — the body reviewing which classes of shortcut repeatedly turned costly reads the record corpus, and those lessons flow back into future intake decisions. What distinguishes it from the register is scope and content: the register is the flat inventory of what debt exists; the record is the durable why behind one item.
Tuning parameters¶
- Template weight — a three-line note versus a structured multi-section document. Lighter templates get written; heavier ones capture more but are skipped under pressure.
- Recording threshold — which decisions warrant a record. Too low a bar buries signal in trivia; too high loses the borderline shortcuts that most need explaining.
- Obligation specificity — how concretely the future cost and repayment are stated. Vague obligations ("clean up later") are unenforceable; specific ones create real accountability.
- Revisit trigger — whether each record carries an explicit condition or date for reconsideration, versus leaving it open-ended.
- Loop closure — whether records are actually harvested in reviews and postmortems, or filed and forgotten.
When it helps, and when it misleads¶
Its strength is preserving rationale before it decays: it is the antidote to the "why on earth is this here?" that makes inherited systems so hard to change, and it is the raw material that lets an organization learn from its own shortcut history rather than repeating it. A real, named practice is Michael Nygard's Architecture Decision Record, a short document capturing the context and consequences of a significant technical decision.[n1]
Its failure mode is ceremony without follow-through: a write-only archive that dutifully records decisions but that no one ever reads, so the learning loop never closes. A subtler failure is recording the decision but not the obligation — capturing "we did X" while omitting the future cost X incurs, which produces a history that looks governed but tracks no debt. The classic misuse is retrofitting records after the fact to justify choices already entrenched, inverting a learning tool into a rationalization engine. The guarding discipline is to keep records short enough to actually write, to insist every one names its obligation and revisit trigger, and to feed the corpus into real reviews so the loop is closed.
How it implements the components¶
debt_definition_boundary— for each recorded decision, the record draws the line: it asserts that this shortcut counts as deliberate, bounded debt and names the obligation that makes it debt rather than mere design.decision_postmortem_loop— the durable corpus of records is what later reviews mine to learn which classes of shortcut turned costly, feeding those lessons back into future intake.
The record documents an accepted shortcut but does not set the gate that decides whether it may be accepted — shortcut_intake_rule is the Debt Budget Review — and it captures one decision's rationale, not the aggregate inventory: debt_register is the Technical Debt Register.
Related¶
- Instantiates: Technical Debt Containment — the record keeps a legitimate shortcut's reasoning and obligation from going invisible.
- Sibling mechanisms: Technical Debt Register · Debt Severity Rubric · Debt Budget Review · Debt-Service Dashboard · Quality or Health Scan · Repayment Reserve · Sunset or Replacement Plan · Exception Expiry Date · Refactoring or Cleanup Sprint
Editorial Notes¶
Form Classification¶
Form family: Record, Log & Register
Rationale: A short, durable record written at the moment a shortcut is taken — naming why it was chosen and what future obligation it creates — so a legitimate expedient never becomes an unexplained, invisible dependency, making its operative form a durable account of actual events, decisions, or transitions whose value depends on history or provenance.
Independent corroboration: The frozen evidence defines Architecture or Process Decision Record as 'A short, durable record written at the moment a shortcut is taken — naming why it was chosen and what future obligation it creates — so a legitimate expedient never becomes an unexplained, invisible dependency', so its operative form is Record, Log & Register.
Review outcome: Independent reviewer agreement; high confidence.
Origin Attribution¶
Primary origin: Computer Science & Software Engineering
Origin pattern: Cross-disciplinary synthesis
Present-day reach: Multi-domain
Rationale: Software ADR practice supplies a short contemporaneous record of context, shortcut, consequences, and revisit trigger.
Related originating lineages:
- Organizational & Management Science — Technical-debt and process-debt management adds a named future obligation.
- Public Administration & Policy — Emergency exceptions and temporary administrative shortcuts provide a nonsoftware application.
Encyclopedia synthesis: The exact catalogued form synthesizes established practice rather than reproducing a single standard historical label.
Review outcome: Independent reviewer agreement; high confidence.
Notes¶
The record is a source, not a consumer — nothing upstream feeds it, which is why it is filed at decision time rather than assembled later. Its distinction from the Exception Expiry Date is worth holding: the record preserves why a shortcut was taken and what it owes; the expiry date polices when the temporary version of it must be resolved. A well-run shortcut often has both — a record naming the obligation and an expiry enforcing its clock.
[n1] An Architecture Decision Record (ADR), popularized by Michael Nygard, is a short, dated document capturing the context, the decision made, and its consequences for one architecturally significant choice. It is a real, widely adopted practice for keeping the reasoning behind a decision durable and findable — the property a decision record contributes to debt containment. ↩