Change Requests (ACR)

An Architecture Change Request (ACR) is the heavyweight path for changing the landscape. It is a named change, bundling one or more entity edits together under a single title and description, that goes to a review board, gets decided, and is then implemented against the current state. Almost everything you do to the landscape can be done as an ACR; whether you should is the question this page answers.

An ACR answers two questions the current-state catalog cannot answer on its own: who agreed to this change and when the change is supposed to land. Between submission and implementation, the proposed state exists side by side with the current state — visible, comparable, and reversible — without the current state being touched.

ACR, per-entity proposal, direct edit

Three ways exist to change the landscape. They exist for different scales of change, not for different roles.

Direct edit — the owner of a single entity changes it in place. The edit takes effect immediately and is recorded in the activity feed. No review, no merge step. Use for routine ownership bookkeeping, attribute corrections, and small changes the owner is accountable for.
Per-entity proposal — a non-owner proposes a change to one specific entity. The proposal sits next to the current state of that one entity until the owner (or an admin) decides on it. Lighter than an ACR: one entity, one owner deciding, no board, no session. Use when you need to suggest a change to an entity you do not own and the change stands on its own.
ACR — a named, scoped change that can cover multiple entities and goes to a review board. Use when the change has cross-entity impact, needs architectural judgement, or is significant enough that it should be named and debated as one thing. An ACR is also the right container when several edits only make sense together — introducing a new application and the integrations that feed it, retiring an IT Component and the applications that consumed it.

The boundary that most often gets drawn wrong: do not use an ACR to rename an entity the owner wants renamed. Do not use a per-entity proposal to introduce a new application together with three integrations and a data object. Pick the path that matches the shape of the change.

What goes into an ACR

An ACR carries a title, a description, and a set of entity changes. The entity changes are the substance: each one is a proposed create, edit, or archive against one entity, held in a draft version separate from the current state. The title and description are the framing — what the change is, why it exists, and what it is supposed to achieve.

An ACR is also associated with a review board. The board is set at submission time and identifies who is authorized to review this particular change. A board’s membership — chair, voting members, advisory members — determines the pool of reviewers. Which session the board uses to review the ACR is a separate decision made by the chair. See Boards & Sessions for the mechanics.

The lifecycle

An ACR moves through a small set of statuses. The transitions between them are the verbs you use on the ACR: submit it, withdraw it, approve it, and so on. The statuses describe where the ACR sits right now; they do not carry history.

stateDiagram-v2
    [*] --> Draft: create
    Draft --> Submitted: submit
    Submitted --> Draft: withdraw
    Submitted --> Approved: approve
    Submitted --> Rejected: reject
    Submitted --> Revision: request_revision
    Revision --> Submitted: resubmit
    Revision --> Draft: withdraw
    Draft --> Cancelled: cancel
    Submitted --> Cancelled: cancel
    Revision --> Cancelled: cancel
    Approved --> Implemented: implement
    Rejected --> Draft: reopen
    Cancelled --> Draft: reopen
    Implemented --> [*]

One point the diagram understates: Rejected and Cancelled are not true terminal states. Both can be reopened back to Draft, at which point the ACR can be edited and resubmitted. The only true terminal state is Implemented — once the proposed edits have been merged into the current state, the ACR cannot be reopened; a follow-on change is a new ACR.

What each status means

Draft — the author is still shaping the change. Entity changes can be added, edited, and removed; the title and description can be rewritten. Nothing is visible to reviewers yet in a reviewable form, because nothing has been submitted.
Submitted — the ACR is on the review board and waiting for a decision. Reviewers can see it, comment on it, and act on it. The author can no longer edit the entity changes; to edit, the author withdraws first.
Revision — a reviewer has asked the author to change something before the board decides. The author is back to editing, and will resubmit when ready. Notes left by the reviewer travel with the ACR.
Approved — the board has accepted the change. Newly-created entities are promoted to current state immediately. Changes to existing entities (modifications, archives) are recorded as Approved but enter a per-owner rollout — they do not appear in the current state until the owner of each affected entity implements their item. See Implementation and rollout below.
Rejected — the board has declined the change. The author can leave it there as a record, or reopen it to rework and try again.
Cancelled — the ACR has been closed without a decision, either by the author or by a reviewer. Like Rejected, it can be reopened if the change is revived later.
Implemented — the proposed edits have been merged into the current state. This is the end of the ACR’s life.

”Under review” is not a status

“Under review” is a common phrase, but it is not a value on the ACR. It is a derived fact: an ACR is under review when it has been placed on the agenda of a session that is currently in progress. The ACR’s own status during that time is Submitted. Moving the ACR onto an agenda, or opening and closing sessions, does not change its status field — it changes whether a session is actively considering it.

This matters because it means the same ACR can be “under review” repeatedly — once per session it is reviewed in — without ever having its status go anywhere other than Submitted → (decision). Filter for “submitted” when you want the queue of ACRs awaiting a decision; filter for “on an in-progress session” when you want the ones being actively discussed right now.

Who can do what

Authorization on an ACR combines four signals: the actor’s workspace role, their relationship to the ACR, the board the ACR is assigned to, and — for ongoing review — the session the ACR has been decided in.

Author actions

The person who created the ACR can submit it, withdraw it after submission (back to Draft), edit it while in Draft or Revision, delete it while in Draft, and reopen it from Rejected or Cancelled. The author cannot approve, reject, or request revision on their own ACR — separation of duties is enforced at the policy layer.

Review authority (approve, reject, request revision)

Review authority is not “any board member”. It comes through two paths:

Board chair. The chair of the ACR’s assigned board can always review — approve, reject, or request revision — with or without tying the decision to a specific review session.
Session reviewers. Once an ACR has been linked to a review session (which happens the first time a reviewer acts on it while passing that session’s identifier along), the session’s chair and its voting participants also gain reviewer rights on that ACR. Advisory participants can comment but not decide.

A voting board member who does not chair the board, and who is not a participant of the session the ACR has been decided in, does not by themselves have approve / reject / revise rights. See Boards & Sessions for the mechanics of how a decision gets linked to a session.

Cancel

Any workspace Contributor or Admin can cancel any ACR, even if they are not the author, not on the board, and not a reviewer. This is deliberate: the workspace as a whole can close out stale or superseded proposals without requiring the author’s cooperation. Like Rejected, a cancelled ACR can be reopened.

Implement

Implementation is per-item, not per-ACR. After an ACR is Approved, each affected entity that was modified or archived enters a rollout state (NeedsPlanning). The owner of that specific entity is authorized to implement their own item. An ACR that touches three applications owned by three different people has three rollout actions, each owned by the respective owner.

Admins additionally control the bulk and override operations: implement all (apply every pending rollout item), stop rollout and resume rollout, and reminder notifications to owners with pending items.

Newly-created entities do not go through this rollout at all — they are promoted to current state at the moment of approval (see the Approved status above).

Admin

Workspace Admins carry every capability on every ACR: author actions, review, cancel, and all implement / rollout operations including bulk and override. This matters in single-admin workspaces: without a carve-out, an Admin who authored an ACR could never get it past the “author cannot review their own” rule. The rule is instead: an Admin can review any ACR, including one they authored themselves. In multi-Admin workspaces the norm is for another Admin to review, but the mechanism does not enforce it.

Comment

Commenting is broader than reviewing: the author, any reviewer (by the rules above), any workspace Admin, and the owner of any entity affected by the ACR can all comment on it. This keeps the author and the people accountable for the affected entities in the same conversation even when those owners are not on the reviewing board.

Editing under copy-on-write

An ACR does not mutate the current state while it is in flight. Every proposed edit — creating a new entity, changing an existing one, archiving one — lives in a draft version held alongside the current state. You can see the current entity and the ACR’s version of it side by side. You can browse the application catalog as it exists today, and then switch to how it would look if this ACR were implemented. Nothing the ACR says about an application affects that application’s current record until the ACR is implemented.

Two properties fall out of this:

Multiple ACRs can touch the same entity at the same time. Each has its own draft version. Whichever is implemented first wins; the others are re-based against the new current state at implementation time.
Withdrawing or rejecting an ACR has no effect on the current state. The draft versions inside it simply cease to be relevant, and the current state is unchanged because it was never changed.

Implementation and rollout

“Implement” does different things depending on what the ACR was changing.

New entities (creations) are promoted to current state at the moment of approval. There is no separate implementation step for them — they exist in the landscape the instant the ACR is approved. The ACR’s approval is their go-live.

Existing entities (modifications, archives) enter rollout. At approval, each affected entity is marked Approved with implementation_status = NeedsPlanning; the change is committed as a decision but is not yet visible in current state. The owner of each affected entity then implements their own item when they are ready. This decoupling exists because approving a change is not the same as being ready to execute it — rollout may need to coordinate with deploys, migrations, handoffs, or communication to downstream consumers.

Per-item rollout authorization:

The owner of the affected entity implements their own item.
Admins can implement any item on any ACR. They also run bulk operations: implement all (apply every pending rollout item in one go), stop and resume rollout on individual items, and reminder notifications to owners with pending items.

The ACR reaches Implemented status once every rolled-out item has been applied (or stopped). Until then, the ACR is Approved with an incomplete rollout.

Activity feed — two entries per change

Each applied change produces two activity-feed entries:

A proposal-scoped entry on the ACR that says the change landed as part of this ACR.
A mainline entry on the entity itself that appears in its history as a regular change — with a link back to the ACR as the reason.

The reason for two entries: a reader on the ACR’s history wants to see every internal event that shaped it, including minor edits inside the ACR. A reader on the application’s history does not want every ACR-internal event, but wants to see the landings — when the entity actually changed — with a way to click through to the reasoning. Keeping the two streams separate lets both audiences read the feed that makes sense to them.

Once Implemented, the ACR is a historical record. It cannot be reopened. A follow-on change is a new ACR.

What makes an ACR reviewable

The three things a reviewer needs:

Coherent scope. Every entity change in the ACR advances the same change. If the ACR introduces a new ERP, every edit should be in service of that introduction — the new application, its integrations, the capabilities it realizes, the IT Components it uses. An ACR that bundles an ERP introduction and an unrelated capability-model cleanup is two ACRs pretending to be one.
Enough context in the description. The title names the change; the description explains it. Why is this happening, what does it achieve, what does it replace, what is the expected impact on the landscape? Reviewers do not have the author’s head. If the description only repeats the title, reviewers are being asked to approve a change they cannot evaluate.
Reviewable size. An ACR that touches five related entities is easy to review. An ACR that touches seventy entities in a single submission is unreviewable — reviewers will either rubber-stamp it or reject it for lack of scrutability. Split large programs into a sequence of smaller ACRs along natural seams (one per affected capability, one per phase), and link them through the containing Initiative.

A reviewable ACR is not a smaller ACR for its own sake. It is one the reviewer can read, understand, decide, and explain the decision for in the time the session allows.

Common modeling mistakes

Bundling unrelated changes into one ACR. A reviewer cannot approve half an ACR. If two independent changes are submitted together, the reviewer has to wait for clarity on both before deciding on either. Split them.
Using an ACR for a routine ownership or attribute fix. An owner changing their own application’s description does not need a board. Direct edit exists for this; using an ACR for it adds friction without adding governance value.
Using a per-entity proposal for a change that spans entities. Introducing a new application that comes with three integrations and a data object is not four separate proposals; it is one ACR. Four separate proposals get decided in four different rooms, and the whole can be approved piecewise into an incoherent state.
Resubmitting instead of withdrawing. An ACR already in Submitted status cannot be edited. If the author discovers a mistake after submission and the reviewer has not yet asked for revision, the right move is to withdraw (back to Draft), fix it, and submit again. “Submitting again” while already submitted is not a thing.
Editing the entity directly “to get around the ACR”. An owner who bypasses a still-pending ACR by editing the entity directly creates a conflict: when the ACR is implemented, the ACR’s proposed version overwrites the direct edit (or is re-based against it, losing the ACR’s intent). Either withdraw the ACR first or wait for it to be decided.
Treating a Rejected ACR as final. Rejected is not final. If the reason for rejection can be addressed, reopen the ACR, adjust it, and resubmit. Creating a near-identical new ACR to avoid the old one’s history hides the reasoning that was already captured.
Naming an ACR after its mechanism, not its intent. “Edit applications and integrations” is a title that tells the reviewer nothing. “Retire legacy CRM and redirect integrations to Salesforce” is a title that frames a decision. Titles are how ACRs are found later; write them for the reader six months from now.

Governance Overview — how ACRs fit alongside boards, sessions, and direct edits
Boards & Sessions — where an ACR is reviewed and by whom
Permissions & Roles — the underlying role and ownership model that authorization on an ACR builds on
Initiatives — the program-level container an ACR often serves
Entities Overview — the entities an ACR’s changes are made against