ADR Change Management Template — Linking ADRs to ITIL and CAB Approvals

The double-documentation problem

When an engineering team introduces ADRs into an organization that already uses ITIL change management, the same architecture decision produces two documents:

• The Architecture Decision Record — written by the engineering team, captures why Postgres was chosen over MongoDB, what was rejected, what trade-offs were accepted. Lives in the code repository.
• The Change Record (CR) — created in ServiceNow, Jira Service Management, or Remedy for the CAB. Contains impact assessment, risk level, rollback plan, deployment window, and approval chain. Lives in the ITSM platform.

The problem: the Change Record's Impact Assessment and the ADR's Consequences section are describing the same thing. Engineers write the Impact Assessment by copying text from the ADR draft. Six months later, the ADR is updated after implementation feedback, but no one remembers to update the closed Change Record. An auditor now sees two documents with conflicting information about the same decision.

The fix is a division of ownership that is respected by both documents from the start.

What each document owns

The governing principle: when a field exists in both documents, the ADR is the source of truth for technical content and the Change Record is the source of truth for process content. Cross-references flow in both directions: the ADR's frontmatter records the Change ID, and the Change Record's Technical Description links to the committed ADR in the code repository.

The ADR-CM template variant

The ADR-CM variant extends the standard Nygard template with four frontmatter fields that create the cross-reference to the ITIL process:

---
title: "Replace Redis session store with database-backed sessions"
status: Accepted
date: 2026-05-15
deciders: ["@alice (tech-lead, Accountable)", "@bob (SRE, Consulted)"]
change-id: CHG0019847
cab-approved: 2026-05-18
emergency-change: false
rollback-tested: true
supersedes: ""
---

## Context
[Standard Nygard Context section — what forced this decision, what constraints apply.]

## Decision
[The choice made and the primary reasoning.]

## Consequences
[Technical consequences: what becomes easier, harder, or different. This section
feeds the Change Record's Impact Assessment. The Change Record references this
section rather than duplicating it.]

## Post-Implementation Review
[Completed after implementation. Required for emergency-change: true. Optional
but encouraged for all ADR-CM records. Documents what actually happened versus
what was predicted in Consequences. If actual consequences match the prediction,
a one-line note — "Consequences matched prediction; no drift." — is sufficient.]

The four additional frontmatter fields serve distinct purposes:

• change-id: — the ITSM Change Record identifier (ServiceNow CHG number, Jira Service Management issue key, Remedy Change ID). Makes the cross-reference machine-searchable: grep -r "change-id" decisions/ produces an inventory of every ADR with a linked Change Record, useful for audit preparation.
• cab-approved: — the date the CAB approved the change. Distinct from the ADR's date: field (the date the ADR was accepted by the engineering team). The gap between the two dates (ADR accepted → CAB approved) is the governance lead time — useful for teams running continuous improvement on their change management process. A consistently long gap suggests the ADR is being written too late in the process.
• emergency-change: — boolean. When true, the Post-Implementation Review section is mandatory and must be completed within 7 days of implementation. CI can enforce this: an ADR with emergency-change: true and no Post-Implementation Review section fails the pipeline after the 7-day window.
• rollback-tested: — boolean. Records whether the rollback procedure was tested before the change was approved. Useful for security audits and PIR analysis when a future rollback is needed. Teams that systematically track this field discover which decision classes have untested rollback plans — typically the ones that cause the longest outages when they fail.

The Change Record template side

When submitting a Change Record for a decision that has an ADR, the Technical Description field should embed the ADR reference in a consistent format:

Technical Description:
This change implements the architecture decision documented in:
ADR file: decisions/0023-replace-redis-session-store.md
ADR permalink: https://gitlab.example.com/engineering/platform/-/blob/main/decisions/0023-replace-redis-session-store.md
ADR-CM status: Accepted (2026-05-15)

Summary of technical approach:
[2–3 sentences summarizing the Decision section — enough context for a CAB member
who has not read the ADR to understand what is changing at a technical level.]

Impact Assessment:
See ADR Consequences section (permalink above) for the authoritative technical
impact description. Business-level risk: [Low/Medium/High — the CAB's risk rating
using your organization's classification scheme, which may differ from the
technical impact assessment]. Teams affected: [list].

Rollback plan:
[Rollback plan lives here in the CR, not in the ADR — rollback is an operational
concern. Reference the ADR's rollback-tested: field value to indicate whether
the procedure has been exercised.]

This structure gives the CAB enough information to make an approval decision without requiring CAB members to read the full ADR, while making clear that the ADR is the authoritative technical source. If the ADR is updated post-implementation (e.g., to add a Post-Implementation Review section), the Change Record's reference automatically points to the current version via the repository permalink.

Emergency change handling

ITIL defines Emergency Changes as changes that must be implemented without the normal CAB review window — typically in response to a production incident or a critical security vulnerability. The standard ADR-CM process breaks down here because there is no time to write an ADR before the change is implemented.

The ADR-EC (Emergency Change) variant handles this with a retroactive workflow:

1. Implement the emergency change. Create an Emergency Change Record in your ITSM platform per your organization's ECAB (Emergency CAB) process. Record the Change ID immediately.
2. Write the ADR-EC within 48 hours. Reconstruct the decision reasoning while it is fresh. The ADR-EC template is identical to the ADR-CM variant with emergency-change: true. The date: field records the implementation date, not the writing date.
3. Submit for engineering review within 48 hours. The normal Accountable-and-Consulted process still applies, but the review window compresses to 48 hours given the post-implementation urgency. The ADR-EC reaches Accepted status after review.
4. Complete the Post-Implementation Review within 7 days. The mandatory PIR section should document: what was predicted in Consequences versus what actually happened, any side effects not anticipated, and whether the emergency change should be superseded by a more permanent solution (which would trigger a new standard ADR).

The 48-hour fidelity window

48 hours is the practical deadline for writing an emergency ADR with useful fidelity. Beyond that window, decision-makers' recollection of the alternatives considered and the trade-offs weighed begins to degrade — the ADR starts to read like a rationalization of what was done rather than a genuine record of what was decided. If the 48-hour window is missed, the ADR-EC should include a retrospective-confidence: low note in the frontmatter to flag that the reasoning was reconstructed from memory and commit messages rather than from contemporaneous notes. Emergency changes without retroactive ADRs are where the most dangerous architectural drift accumulates: the system evolves in ways that no document explains.

Platform-specific notes

ServiceNow

ServiceNow's standard Change Request form has a Justification field and an Implementation Notes field. Put the ADR's repository permalink in Justification and the rollback plan in Implementation Notes. ServiceNow does not have a native "link to external document" relation type — the permalink in a text field is the best available cross-reference. If your ServiceNow instance has the Configuration Management Database (CMDB) module, link the Change Request to the Configuration Item (CI) representing the affected service and add a custom attribute to the CI for "ADR last updated" to make the cross-reference machine-readable across CMDB queries.

Jira Service Management

JSM's Change Management project type supports custom fields. Add a "Related ADR" URL field to the Change Request Issue type. This makes the link structured and queryable via JQL: issuetype = "Change" AND "Related ADR" is not EMPTY ORDER BY created DESC. Use the Jira Issue Links "is documented by" relation (or a custom "is governed by" relation if configured) to connect the Change Issue to the Jira Issue tracking the ADR PR review. The bidirectional link allows a developer looking at the engineering Jira issue to navigate directly to the Change Record without searching ServiceNow or Remedy.

Remedy / BMC Helix

Remedy's Change Management module has configurable text fields alongside the standard Description field. Use the Work Order Notes or a custom "Architecture Reference" field for the ADR permalink. Remedy's REST API allows querying Change Records by custom field value — a nightly script that aggregates all Change Records with non-empty Architecture Reference fields produces a cross-reference inventory without manual tracking, useful when preparing for SOC 2 or ISO 27001 audit evidence collection.

Connecting AI-assisted decisions to the audit trail

Architecture decisions that go through ITIL change management often have the longest paper trails — they are the decisions most likely to be audited, contested, or revisited. They are also, increasingly, decisions that were partially developed in ChatGPT or Claude sessions before the ADR was written.

The gap: the AI-chat session where trade-offs were explored is invisible to the CAB reviewer, the auditor, and the future engineer. The ADR captures the conclusion; the Change Record captures the approval; but the deliberation — including alternatives rejected and risks accepted — lives in an ephemeral chat session.

Two practices close this gap for governed decisions:

1. Extract the decision record from the AI chat session using WhyChose before writing the ADR. The extracted record includes the alternatives considered and the trade-offs discussed — this becomes the raw material for the ADR's Context and Decision sections, and it is far richer than what an engineer typically writes from memory after the fact.
2. Link the extracted record in the ADR's deliberation field. Add a deliberation-record: field to your ADR-CM template pointing to the WhyChose-exported record or a share link to the relevant conversation. When the auditor asks "why was this option chosen over the alternative?", the answer is a link, not a memory.

Get early access to WhyChose

Related questions

Further reading

• ADR decision authority matrix — who writes, reviews, and approves — the engineering governance layer that sits beneath the CAB approval layer. For CAB-reviewed decisions, two approval chains apply: the engineering authority matrix (who marks the ADR Accepted) and the ITIL change management chain (who authorizes the Change Record). The two pages describe complementary governance layers: the authority matrix governs the engineering approval, this page governs the change management integration.
• ADR review checklist — what to look for before merging an architecture decision record — the review checklist that Accountable reviewers run before marking an ADR Accepted. In change-managed environments, the Consequences section of the checklist carries extra weight because it feeds the Change Record's Impact Assessment before CAB submission — an incomplete Consequences section blocks both engineering acceptance and Change Record submission.
• Architecture decision record best practices — the synthesis page for ADR governance disciplines. Change management integration is an advanced practice that applies on top of the foundational practices (numbering, supersession, link hygiene, review cadence) covered in best practices — adopt the fundamentals before layering on the ITIL integration.
• ADR vs RFC — when to use each and how they work together — in ITIL environments, the RFC (Request for Change) is sometimes confused with both the ADR and the ITIL Change Record. The ADR vs RFC page clarifies where each document type sits in the decision lifecycle; this page extends that picture with the ITIL Change Record as the third document in the governance chain for significant architecture changes.
• When to write an ADR (and when you shouldn't) — a useful heuristic for change-managed environments: any change that requires a CAB-approved Change Record also warrants an ADR. Not all ADRs require Change Records (a library upgrade scoped to one service may not meet your organization's change threshold), but all CAB-reviewed changes are significant enough to document as architecture decisions. The threshold page's impact-radius rules align with ITIL's risk-classification framework.