Decision Records

Why Decisions Need Recording

Here's what happens without decision records: someone makes an architecture decision during a project. It makes sense at the time. The people in the room understand the context, the constraints, the trade-offs. The project ships. Everyone moves on.

Three years later, a new team inherits the system. They look at a particular design choice and think: "Why on earth would anyone do it this way?" Without context, the decision looks incompetent. So they change it. And in doing so, they reintroduce the exact problem the original decision was designed to solve — because they didn't know the problem existed.

Or worse: nobody changes anything, because nobody's confident enough to touch a system they don't understand. Technical debt accumulates. The system becomes increasingly fragile. Eventually it fails, and nobody can explain why it was built that way in the first place.

Decision records fix this. Not by creating bureaucratic documentation that nobody reads, but by capturing just enough context that future teams can understand why things are the way they are.

What a Decision Record Is (and Isn't)

A decision record is a lightweight artefact that captures the essential context around a significant architecture decision. It's designed to be:

✅ Quick to complete — 15 minutes, not half a day
✅ Easy to find — stored with the system, not buried in project archives
✅ Useful to read — answers the questions future teams will actually ask
✅ Living — updated when circumstances change or decisions are revisited

A decision record is not:

❌ A 50-page architecture document
❌ A formal approval request
❌ A compliance checkbox exercise
❌ Something you write after the fact to cover yourself

The goal is traceability, not bureaucracy. When someone looks at this system in three years, they should be able to understand why it was built this way — and make an informed choice about whether to change it.

When to Create a Decision Record

Not every decision needs a record. You don't need to document which variable naming convention you used or why you chose tabs over spaces.

Create a decision record when:

The decision affects system architecture — components, integration patterns, technology choices, data flows
The decision involves trade-offs — you're choosing between competing options with different strengths and weaknesses
The decision deviates from guardrails — you're consciously stepping outside established standards
The decision introduces technical debt — you're making a pragmatic choice that will need future remediation
Someone might reasonably ask "why?" — if a future team would question this choice, document it now
The decision is hard to reverse — lock-in, significant refactoring required, contractual commitments

As a rule of thumb: if you had a conversation about whether to do it this way or that way, and the answer wasn't immediately obvious, that's probably worth recording.

What to Capture

A decision record answers four questions:

1. What decision was made?

State the decision clearly and specifically. Not "we decided on the integration approach" but "we will use event-driven integration via Azure Service Bus for order processing, with REST APIs for synchronous queries."

Be concrete. Someone reading this should understand exactly what was decided without having to interpret vague language.

2. What options were considered?

List the alternatives you evaluated, even briefly. This isn't about proving you did your homework — it's about helping future teams understand the decision space.

For each option, note:

What it would have involved
Key advantages
Key disadvantages or risks
Why it wasn't selected (if it wasn't)

You don't need exhaustive analysis. A few sentences per option is usually enough. The point is that someone reading this can see you considered alternatives and understand why this option won.

3. What guardrails does this touch?

Explicitly link the decision to the relevant guardrails:

Aligned — the decision follows established guardrails (note which ones)
Deviation — the decision steps outside guardrails (note which ones and why)

This creates traceability between individual decisions and enterprise architecture direction. It also makes guardrail compliance visible without requiring separate compliance tracking.

If the decision is a deviation, capture:

Which guardrail(s) it deviates from
Why the deviation is justified
Who accepted the deviation (appropriate to the tier)
Any conditions or timeframes on the deviation

4. What debt does this introduce?

Be honest about trade-offs. If this decision creates technical debt, acknowledge it:

What debt is being introduced?
Why is this acceptable? (timeline, cost, uncertainty, etc.)
What's the estimated effort to remediate?
When should this debt be addressed?
Who owns tracking this debt?

Decisions that introduce debt aren't bad decisions — sometimes they're exactly the right call. But invisible debt is unmanaged risk. Recording it here ensures it flows into the debt register and stays visible.

Where Decision Records Live

Decision records should be:

Stored with the system — not in a separate architecture repository that nobody looks at
Linked from the Architecture Passport — the passport summarises key decisions and links to the full records
Discoverable — tagged, indexed, or organised so they can be found
Version controlled — changes tracked, history preserved

Practically, this often means:

In the code repository (for technical decisions close to implementation)
In the system's documentation space (Confluence, SharePoint, wiki)
Referenced in the Architecture Passport
Custom task type in project delivery tool (e.g., Jira or Azure DevOps Boards)

The worst place for decision records is buried in project documentation that gets archived when the project closes. Decisions belong with systems, not with projects.

Decision Record Lifecycle

Decisions aren't permanent. Circumstances change. What made sense two years ago might not make sense today.

Proposed: Decision is drafted but not yet accepted. Used for significant decisions that need review or approval before implementation.

Accepted: Decision is in effect. This is the normal state for active decisions.

Superseded: A new decision has replaced this one. Link to the new decision record. Keep the old record for historical context — understanding why we used to do something this way can be as valuable as understanding why we do it the current way.

Deprecated: Decision is no longer relevant — the system has changed, the technology has been retired, the context no longer applies. Archive but don't delete.

When revisiting a decision:

Create a new decision record (don't just edit the old one)
Reference the original decision
Explain what changed — new information, changed constraints, different priorities
Mark the original as superseded

This preserves the decision history. You can trace how architectural thinking evolved over time.

Common Pitfalls

Writing records after the fact to justify decisions already made

Decision records should capture actual deliberation, not post-hoc rationalisation. If you're writing a record to explain a decision you made six months ago, be honest that you're reconstructing context — and acknowledge if you've forgotten why certain choices were made.

Too much detail

If your decision records routinely take hours to write, they're too detailed. Future readers need context and rationale, not exhaustive analysis. Summarise. Link to supporting documents if deeper detail exists elsewhere.

Too little detail

"We decided to use Kubernetes" isn't a decision record. Why Kubernetes? What were the alternatives? What trade-offs did you accept? A decision record with no rationale is just a statement of fact — it doesn't help future teams understand anything.

Treating records as approval gates

Decision records document decisions — they're not approval requests. If your process requires approval, that's a separate mechanism. Don't let decision records become another bottleneck.

Forgetting to update when things change

A decision record that says "we chose X" when the system actually uses Y is worse than no record at all. When decisions are revisited or reversed, update the records. Mark superseded decisions. Keep the documentation honest.

The Decision Records Promise

Without decision records, every architecture conversation starts with the same questions:

"Why did we build it this way?"
"What else did they consider?"
"Is this deliberate or accidental?"
"Can we change it, or will something break?"
"Who decided this, and are they still here?"

With decision records, those questions have answers. Not perfect answers — but enough context to make informed choices rather than nervous guesses.

Fifteen minutes of documentation now saves hours of archaeology later. More importantly, it saves the slow accumulation of fear that happens when nobody understands why things are the way they are.

Decision records aren't bureaucracy. They're institutional memory. They're the difference between building on foundations and building on mysteries.

Getting Started

If you don't have decision records today, don't try to document every historical decision. That way lies madness.

Instead:

Start now — new decisions get records, starting today
Document when you touch — when you work on a system and discover undocumented decisions, record what you learn
Prioritise mysteries — if there's a design choice that everyone wonders about, investigate and document it
Keep it simple — use a lightweight template, iterate based on what's actually useful

Within six months, you'll have a growing body of decision context. Within a year, the culture shift takes hold — documenting decisions becomes normal, not extra work.

The goal isn't perfect historical documentation. It's a practice that captures decisions going forward so you stop losing architectural knowledge every time someone moves on.

XAF Connected Architecture | Developed by InnovateX Solutions