The Wrong Instrument for the Job

A hospital has one patient.

But it does not have one type of record.

The ICU chart captures minute-by-minute vitals.

The surgical report captures every incision, every finding, every closure decision.

The outpatient note captures a 10-minute consultation.

The discharge summary captures what changed and what happens next.

Same institution.

Same patient data.

Four different record formats.

Because the context is different.

The stakes are different.

The audience is different.

The consequences of an incomplete record are different.

Now look at how most engineering organisations manage architectural decisions.

One template.

Every decision.

Every team.

Every context.

The result is predictable.

High-stakes decisions get shallow records because the template asks for things that do not apply.

Routine decisions get skipped entirely because the template feels like too much overhead.

AI agent decisions do not get recorded at all because nobody built a template for them.

And the architecture register slowly fills with noise, gaps, and outdated entries that nobody trusts.

The problem is not that engineers avoid documentation.

The problem is that one template cannot serve five different decision contexts.

What Makes a Decision Context Different

Before building templates, the dimensions of difference need to be named.

A decision context is defined by four variables:

Reversibility — how costly is it to undo?
Blast radius — how many systems or teams are affected?
Decision origin — human or agent?
Velocity requirement — does this need to be decided in hours or months?

%% caption: How the same decision moves through intent, architecture and delivery
quadrantChart
    title ADR Context Map
    x-axis Low Blast Radius --> High Blast Radius
    y-axis Low Reversibility Cost --> High Reversibility Cost
    quadrant-1 Cross-Domain ADR
    quadrant-2 Risk-Weighted ADR
    quadrant-3 Lightweight ADR
    quadrant-4 Standard ADR

Each quadrant needs a different record.

Not a different tone.

A different structure.

The Contextual Decision Record Stack (CDRS)

The Contextual Decision Record Stack (CDRS) is a five-template model where each template matches a specific decision context.

The five templates are:

Template	Context	Decision Origin	Blast Radius	Reversibility
Standard ADR	Routine architectural choices	Human	Single system	Medium
Lightweight ADR	Fast-delivery, low-stakes	Human	Single component	High
Risk-Weighted ADR	High-stakes, irreversible	Human	Organisation-wide	Very Low
Cross-Domain ADR	Decisions spanning bounded contexts	Human (multi-team)	Multiple systems	Low
Agentic ADR	AI agent structural decisions	Agent-proposed, human-confirmed	Variable	Variable

Each template covers different fields.

Each template triggers different governance.

Template 1 — Standard ADR

Context: The everyday architectural decision.
A technology choice. An integration pattern. A data model shape.
Affects one system. Reversible within a sprint. Made by one architect or team.

# ADR-[NUMBER]: [TITLE]

## Status
[ ] Proposed | [ ] Accepted | [ ] Deprecated | [ ] Superseded by ADR-[N]

## Date
YYYY-MM-DD

## Decision Makers
- [Name, Role]

## Context
What situation requires a decision?
What constraints or forces are in play?

## Decision
What was decided?
State it in one sentence.

## Rationale
Why this option over others?
What alternatives were considered?

## Consequences
### Positive
- [Expected benefit]

### Negative
- [Known trade-off]

## Compliance
- Does this decision require security review? [ ] Yes [ ] No
- Does this decision require data governance sign-off? [ ] Yes [ ] No

## Review Date
YYYY-MM-DD

Governance trigger: Auto-commit to ADR register on merge.
Review cycle: Quarterly.

Template 2 — Lightweight ADR

Context: Fast-moving teams. Short sprint cycles. Low-risk, reversible choices.
The goal is capture, not ceremony.
This template takes five minutes to complete.
If it takes longer, the decision belongs in a different template.

# ADR-[NUMBER]: [TITLE]

## Status
[ ] Accepted | [ ] Superseded

## Date
YYYY-MM-DD

## Decision
One sentence. What was decided?

## Why This, Not That
One to three bullets. Why not the obvious alternative?

## Undo Cost
[ ] Low — revert in hours
[ ] Medium — revert in a sprint
[ ] High — requires rework cycle (wrong template, escalate)

## Owner
[Name]

Governance trigger: Linter check on PR. Flags if Undo Cost = High.
Review cycle: Per sprint retrospective.

Template 3 — Risk-Weighted ADR

Context: Decisions that are difficult or impossible to reverse.
Infrastructure changes. Authentication patterns. Published event schemas.
Shared contracts. Platform selection.

This template requires more fields because the cost of a poor record is proportional to the cost of undoing the decision.

# ADR-[NUMBER]: [TITLE]

## Status
[ ] Under Review | [ ] Approved | [ ] Rejected | [ ] Superseded by ADR-[N]

## Date
YYYY-MM-DD

## Decision Class
[ ] Infrastructure | [ ] Security | [ ] Data Contract | [ ] Platform | [ ] Integration Pattern

## Decision Makers
- [Name, Role, Authority Level]

## Approvers Required
- [ ] Architecture Lead
- [ ] Security Review Board
- [ ] Data Governance
- [ ] CTO / CIO sign-off

## Context
What forces make this decision necessary?
What happens if this decision is deferred?

## Decision
State the decision precisely.
Include the version, pattern name, or standard being adopted.

## Alternatives Evaluated

| Option | Pros | Cons | Ruled Out Because |
|--------|------|------|-------------------|
| Option A | | | |
| Option B | | | |
| Option C (selected) | | | |

## Risk Assessment

| Risk | Likelihood | Impact | Mitigation |
|------|------------|--------|------------|
| | | | |

## Reversal Cost
What would it take to undo this decision in:
- 6 months?
- 2 years?

## Consequences
### Structural
### Operational
### Financial

## Dependencies Created
List every downstream system or team that will be structurally affected.

## Review Trigger
This decision must be re-evaluated if:
- [Condition 1]
- [Condition 2]

Governance trigger: Blocked from merge until all Approvers Required are checked.
Review cycle: Annually, or when a review trigger condition is met.

Template 4 — Cross-Domain ADR

Context: Decisions that cross bounded context boundaries.
Two or more teams own systems affected by this decision.
A shared schema. A new event contract. A cross-service API pattern.

The problem this template solves is not documentation.

It is accountability.

When a decision affects three teams, every team assumes another team owns the record.

The Cross-Domain ADR names every owner explicitly.

# ADR-[NUMBER]: [TITLE]

## Status
[ ] Proposed | [ ] In Consultation | [ ] Accepted | [ ] Superseded

## Date
YYYY-MM-DD

## Originating Team
[Team Name]

## Affected Bounded Contexts

| Context | Owning Team | Representative | Impact |
|---------|-------------|----------------|--------|
| | | | |

## Consultation Status

| Team | Consulted | Response | Date |
|------|-----------|----------|------|
| | [ ] Yes / [ ] Pending | | |

## Decision
What was decided across domain boundaries?

## Integration Contract
If this decision establishes or modifies a shared contract:
- Contract type: [ ] API | [ ] Event Schema | [ ] Data Model | [ ] Shared Library
- Version:
- Breaking change: [ ] Yes | [ ] No
- Migration path:

## Rationale
Why was this the agreed approach?
What did each team trade off?

## Consequences Per Domain

| Domain | Benefit | Cost | Owner of Transition |
|--------|---------|------|---------------------|
| | | | |

## Escalation Path
If any team disagrees, who breaks the deadlock?
[Name, Role]

## Review Date
YYYY-MM-DD

Governance trigger: PR cannot merge until all affected teams have checked Consulted = Yes.
Review cycle: On every breaking contract change.

Template 5 — Agentic ADR

Context: AI agent decisions that affect system structure.
This template exists because agents are already making architecture decisions in production.

The Agentic ADR is the formal record of a Zone B decision from the Agent Decision Perimeter model.

The agent proposes.

A human architect confirms.

The ADR is the gate between proposal and execution.

Without this template, agent structural decisions remain unrecorded, unreviewed, and invisible to every future architect who inherits the system.

# ADR-[NUMBER]: [TITLE] (Agent-Proposed)

## Status
[ ] Agent-Proposed | [ ] Architect-Confirmed | [ ] Rejected | [ ] Superseded

## Date
YYYY-MM-DD

## Agent Identity
- Agent name/ID:
- Agent version:
- Orchestration system:

## ADP Zone Classification
[ ] Zone B — Propose + Confirm (correct for this template)
[ ] Zone C — Escalate to Human Only (wrong template, do not proceed)

## Decision Proposed by Agent
What structural decision did the agent propose?
State it exactly as the agent surfaced it.

## Context at Time of Decision
- What task was the agent executing?
- What condition triggered the structural choice?
- What alternatives did the agent evaluate?

## Structural Impact
- Systems affected:
- Interfaces modified:
- Dependencies introduced:
- Reversibility: [ ] Within sprint | [ ] Requires rework cycle

## Human Architect Review
- Reviewed by: [Name]
- Review date: YYYY-MM-DD
- Decision: [ ] Accepted | [ ] Rejected | [ ] Modified

## Modification (if applicable)
If the architect modified the agent's proposal:
What changed and why?

## Consequences
### Intended
### Risks if agent repeats this pattern without review

## Automation Rule Update
Should this decision class be moved to Zone A (autonomous) in the future?
[ ] Yes — update agent configuration
[ ] No — continue Zone B review for this class

## Audit Trail
- Agent action log reference:
- Governance system ticket:

Governance trigger: Agent execution blocked until Architect-Confirmed status is set.
Review cycle: Per agent deployment cycle, and quarterly zone reclassification.

The CDRS Decision Router

The right template must be selected before documentation begins.

This router removes the guesswork.

%% caption: The CDRS router: which of the five ADR templates a decision needs, asked in order
flowchart TD
    A["New Architecture Decision"] --> B{"Was this decision made\nor proposed by an AI agent?"}
    B -- Yes --> T5["Agentic ADR\n(Template 5)"]
    B -- No --> C{"Does it affect more\nthan one bounded context?"}
    C -- Yes --> T4["Cross-Domain ADR\n(Template 4)"]
    C -- No --> D{"Is reversal cost\nhigh or very high?"}
    D -- Yes --> T3["Risk-Weighted ADR\n(Template 3)"]
    D -- No --> E{"Does the team need\nto move in under 24 hours?"}
    E -- Yes --> T2["Lightweight ADR\n(Template 2)"]
    E -- No --> T1["Standard ADR\n(Template 1)"]

Print this.

Put it in every architecture onboarding guide.

Stop debating which template to use at the start of a decision.

Route first.

Write second.

Governance Automation

Templates without automation produce ADR registers that are incomplete within three months.

Not because engineers are lazy.

Because manual follow-up is a losing architecture.

Five automation rules close the gap.

Rule 1 — ADR Linting on Pull Request

Install an ADR linter in your CI pipeline.

The linter checks:

Is the status field populated?
Is the decision field a single sentence or less?
For Lightweight ADRs: is the Undo Cost field checked?
For Risk-Weighted ADRs: are all Approvers Required fields populated?

Tools that support this pattern: adr-tools, log4brains, custom GitHub Actions.

If the lint fails, the PR is blocked.

Not as a punishment.

As a gate.

Rule 2 — Automated Review Date Reminders

Every Standard and Risk-Weighted ADR has a Review Date field.

Automate a reminder 30 days before that date.

The reminder goes to the Decision Maker named in the ADR.

Not to a shared channel.

Not to a generic team alias.

To the named person.

If no action is taken within two weeks, the ADR status automatically changes to Stale.

Stale ADRs appear in the architecture dashboard.

Rule 3 — Cross-Domain Consultation Gate

For Cross-Domain ADRs, a GitHub Action reads the Affected Bounded Contexts table.

It creates a review request for the representative of each affected team.

The PR merge is blocked until every representative has added their approval.

This is not bureaucracy.

This is dependency management applied to governance.

Rule 4 — Agentic ADR Auto-Generation

When an agent makes a Zone B decision, the orchestration system auto-generates an Agentic ADR draft.

The draft is pre-populated with:

Agent identity
Decision proposed
Structural impact (from the agent's reasoning trace)
Audit trail reference

The architect does not start from a blank template.

They review a pre-filled record.

They confirm or modify.

The gate opens.

This one change removes the biggest reason Agentic ADRs do not get written.

It is not that architects are unwilling.

It is that starting from blank is overhead nobody has time for.

Rule 5 — Architecture Drift Detection

Every merged ADR updates a machine-readable decision register.

A weekly job compares:

Decisions recorded in the register
System topology captured by observability tooling

When a dependency appears in the topology that has no corresponding ADR, a drift alert is raised.

Not a failed build.

A named alert.

"Dependency detected between Service A and Service B. No ADR found for this integration."

The responsible team has 72 hours to classify the decision and record it.

This is governance that watches the system.

Not governance that watches the calendar.

The Governance Automation Stack

%% caption: The governance automation stack: ADR linting, the register, review reminders, cross-domain gates and drift detection
flowchart TB
    A["Developer writes ADR"] --> B["ADR Linter\n(CI/CD Gate)"]
    B --> C["ADR merged to register"]
    C --> D["Review Date Tracker\n(Automated Reminders)"]
    C --> E["Cross-Domain Gate\n(Multi-team Approval)"]
    C --> F["Topology Comparator\n(Drift Detection)"]

    G["Agent makes\nZone B decision"] --> H["Auto-generated\nAgentic ADR Draft"]
    H --> I["Architect Review\nGate"]
    I --> C

The automation stack does not replace architect judgment.

It removes the friction that causes architect judgment to go unrecorded.

What Breaks Without CDRS

One Template Produces False Confidence

When a single template is used for every decision, architects start skipping fields.

They skip fields because the fields do not apply.

But skipping fields looks identical to incomplete documentation.

Future architects cannot tell the difference between a field that was skipped because it was irrelevant and a field that was skipped because the decision was rushed.

The register becomes untrustworthy.

No Agentic Template Means No Agentic Record

If the ADR system was designed before AI agents were in production, it was designed for human decisions.

Agents will not file ADRs because no template exists for them.

The architecture will drift in ways no review board ever sees.

No Automation Means Decay

Every ADR system that relies on manual discipline eventually decays.

Not because the architects are undisciplined.

Because manual systems compete with delivery pressure.

Delivery pressure wins.

Automation removes the competition.

Evidence from Practice

A SaaS scale-up I worked with had grown from 15 to 80 engineers in 18 months. Their architecture review meetings had become the organisation's primary bottleneck — every decision required a cross-team meeting, meetings were scheduled weeks out, and decisions were revisited because nothing was documented. The VP Engineering estimated that 30% of engineering capacity was lost to architecture debate that never reached resolution.

We introduced five ADR templates covering different decision contexts, a decision rights matrix mapping decision types to deciders, and a fortnightly architecture sync. Decision cycle time dropped from 2–4 weeks to 2–5 days. The ADR log became a source of truth that new hires read to understand past decisions. The VP Engineering described it as "the single highest-leverage process change we made in two years."

The full case study is available here: Reducing Architecture Decision Time by 60%

Implementation Guide (30–60 Days)

Phase 1: Audit the Current Register (Weeks 1–2)

Review every ADR in the existing register.

For each one, identify:

Which of the five CDRS templates should have been used?
What fields are missing that would have been captured by the right template?
Are there decisions in production that have no ADR at all?

Deliverable: ADR gap analysis by decision type
Success Metric: At least one example of an unrecorded decision in each CDRS category

Phase 2: Deploy the Template Set (Weeks 3–4)

Replace the single template with the five CDRS templates.

Add the decision router to the architecture documentation and onboarding guide.

Run one training session with all architecture leads.

Not to explain the templates.

To route three real decisions from the backlog together.

Deliverable: Five templates live in the repository, router published
Success Metric: Next five ADRs filed use the correct template without prompting

Phase 3: Automate the Governance Layer (Weeks 5–8)

Implement the five automation rules in sequence.

Start with ADR linting.

It is the fastest to deploy and the highest-leverage gate.

Then add review date tracking.

Then the cross-domain consultation gate.

Save drift detection for last — it requires observability tooling integration.

Deliverable: At least three of the five automation rules live in CI/CD
Success Metric: Zero manually chased ADR reviews in the first 30 days after automation goes live

Action Plan

This Week

Ask three questions about your current ADR register:

Does every ADR in the register use the same template regardless of decision type?
Are there AI agent decisions currently running in production that have no ADR?
How many ADRs past their Review Date have not been revisited?

If any answer is uncomfortable, the CDRS is the structural fix.

Next 30 Days

Deploy the five templates in your ADR repository
Route your next 10 decisions through the decision router
Add an ADR linter to your CI pipeline

3–6 Months

Automate all five governance rules
Integrate agent orchestration systems with Agentic ADR auto-generation
Add architecture drift detection to your observability pipeline
Run a quarterly ADR audit using the CDRS gap analysis method

Final Thought

The hospital does not use one form for every patient interaction.

Not because it is bureaucratic.

Because the stakes are different.

The context is different.

The audience is different.

One form for every situation does not produce complete records.

It produces records that look complete but are not.

Your architecture decisions deserve the same clarity.

Not one template.

The right template for the decision in front of you.

That is the difference between a register that is trusted and one that is merely maintained.

Build an ADR System That Your Architecture Actually Trusts

If your ADR register is filled with skipped fields and outdated records…
if agent decisions in production have no documentation at all…
or if ADR governance depends entirely on manual follow-up that delivery pressure keeps winning against —

the problem is not discipline.

It is template fit and structural automation.

In a focused 30-minute Architecture Documentation Diagnostic, we will:

Audit your current ADR register against CDRS decision types
Identify which decisions are structurally underdocumented
Design the right template set for your organisation's decision profile
Define a 30-day automation plan that removes manual governance overhead

No bloated documentation frameworks.
No process ceremonies nobody attends.
Just an ADR system that captures the decisions your architecture actually depends on.

→ Book an ADR Governance Session

→ Contact me directly

The right record for the right decision.

That is the only governance model that survives delivery pressure.

ADR Templates: 5 Variations for Different Contexts + Governance Automation