Direct answer: Require an architecture diagram update when a change alters a fact that an authoritative diagram claims to show. In the pull request, link the updated source or version; if no update is needed, give a reason tied to that diagram’s scope. CI can validate diagram files, generated output, and declared code ownership. It cannot reliably decide from arbitrary code changes whether a diagram is now conceptually wrong.
A useful policy says what the diagram covers, what changes trigger an update, and what evidence reviewers expect. “Update docs” and a checked box do not answer whether the author compared the design with the implementation.
Decide whether this belongs in the Definition of Done
In Scrum, the Definition of Done is the commitment describing the quality state of an Increment. The Scrum Guide says an organizational standard is the minimum for teams that use it; where there is no organizational standard, the Scrum Team creates a Definition of Done appropriate to the product. So include diagram currency there when it is a quality condition every Increment must meet. If only architecture-affecting work triggers an update, make the condition explicit rather than requiring every pull request to edit a diagram.
Teams that do not use Scrum can put the same rule in a pull request template, engineering policy, or change checklist. The important point is to define the trigger and evidence before reviewers apply it inconsistently.
Define the scope of each authoritative diagram
A diagram can only be kept current against a stated scope. For each maintained view, write down what it represents, who owns it, and where its editable source lives. For example: “The checkout runtime map shows service boundaries, event topics, persistent stores, trust boundaries, and retry paths; it does not show class structure or UI screens.”
This scope makes the update decision testable. Ask: Would leaving this view unchanged mislead someone making an operational, security, ownership, or design decision? If not, the code change may be real without changing that diagram. The team may have another document to update, but a diagram rule should not become a vague mandate to update all documentation.
A practical trigger table looks like this:
| Change | Update the diagram when… | Evidence in the pull request |
|---|---|---|
| A new service, worker, API call, queue, or event consumer is added | The view documents that boundary or relationship | Link the changed view and identify the new component or edge |
| Data storage, movement, or access changes | The view includes those stores, flows, or trust boundaries | Point to the changed data path and the relevant owner or review |
| Retry, timeout, failover, or deployment behavior changes | The view claims to represent that runtime or operational behavior | Show the changed path, or explain why it is below the diagram’s level of detail |
| A private function is renamed or code is refactored inside an existing component | No represented boundary, relationship, or behavior changes | State “no diagram update” and name the unchanged scope |
| UI copy, tests, or a local bug fix changes | The authoritative diagram does not represent the affected detail | State why the view remains accurate |
These are examples, not universal classifications. A queue retry may be significant in a failure-handling diagram and irrelevant in a high-level system context view. The diagram’s declared purpose decides. For a starter set of views and their roles, see minimum viable architecture documentation.
Make the update part of the same change
For design-led work, update the proposed view during design review, then compare it with the implementation before merge. For an implementation-led change, update the diagram in the same pull request or linked work item that changes the represented facts. Do not leave “update the diagram later” as an unowned follow-up.
If a design changes after review, record the new decision and update the view that claims to represent the accepted state. Keep proposed, accepted, and deployed states distinguishable; a picture of a target design should not silently appear to describe production. The team’s diagram review process can define who checks that distinction.
Ask for evidence instead of a checkbox
A pull request template should let the author describe the impact without pretending that Markdown checkboxes enforce a choice. For example:
## Architecture impact
Diagram or source of truth: <link, or “none affected”>
Evidence: <updated file/version and change, or why the current view remains accurate>
Review: <owner or reviewer, when the diagram's scope requires it>
For an internal rename, a useful response is: “No diagram update: this refactor stays inside the existing worker; the checkout map shows service boundaries and external flows.” For a new event consumer, the response links the flow view and identifies the new producer-to-consumer edge. A reviewer can then challenge the reasoning instead of checking an unexplained box.
Keep the evidence proportional. A low-level code-only change may need one sentence. A new boundary may need a source diff, a link to a decision, and review from the team that owns the affected system. A pull request field records the claim; it does not prove the diagram matches the code.
Automate checks CI can actually prove
| Repository setup | Useful automated check | What the result proves |
|---|---|---|
| Mermaid source is committed | Render each changed .mmd file with a pinned Mermaid CLI version; for example, mmdc -i docs/architecture/checkout.mmd -o /tmp/checkout.svg |
The source parses and renders with that tool version, not that its edges match the running system. The official Mermaid CLI documents this input-to-SVG command. |
| Diagrams or images are generated from source | Regenerate them in CI and fail if the committed output differs | The stored output matches the generator’s current output, assuming the build is deterministic. |
| Diagram files have named owners | Use CODEOWNERS to request an owner review for changes to those files |
GitHub can request review automatically; merge blocking requires the repository to enable required code-owner approval in its branch protection or ruleset. See GitHub’s CODEOWNERS behavior and protected-branch review settings. |
| A code change may alter a system relationship without changing an obvious file | Ask for impact evidence and have a reviewer compare the relevant view with the diff | A person has assessed the declared scope; CI has not inferred architecture semantics. |
A syntax check catches malformed Mermaid, not missing components, outdated labels, or incorrect direction. A generated-output check catches stale files only when the generation input and process are defined. CODEOWNERS routes a review request; it does not by itself make an approval mandatory. Enable that separately only for paths where owner review should block merging.
Avoid requiring an Architecture Decision Record (ADR) for every contract or dependency change. Require one when the team’s decision policy says the change needs a durable record—for example, because it establishes a cross-team boundary or selects between consequential alternatives. A version bump alone does not prove that an architectural decision occurred. Link the ADR policy or decision record when it applies.
Apply the rule to two pull requests
Internal refactor: A developer renames a handler and changes its local implementation. The system map shows only the worker boundary and its message-broker relationship; both remain the same. The PR says no diagram update is needed and explains why. No diagram edit is required just to refresh a date.
New consumer: A change adds a fraud-scoring service that consumes checkout events. If the architecture view documents event flows, update it to show the consumer, the relevant relationship, and ownership. Include retry or failure behavior only if that view claims to cover it. Link a decision record if the new boundary required one; do not treat the diagram or PR approval as proof that the design was formally accepted.
The rule works because it asks whether a diagram’s stated claim is still true, not whether the diff looks large. A small code change can add a consequential relationship, while a large refactor can preserve every relationship in a high-level map.
Keep a Slack design review connected to the pull request
When the design discussion happens in Slack, link the specific diagram version reviewed for implementation in the pull request. Arialine supports addressed edits in a board thread; its numbered versions link back to the Slack message that caused each change. The reviewer can use that trail as design evidence, then compare the Mermaid source with the code. How Arialine edits a diagram from its Slack thread.
If the repository owns the maintained diagram, export its Mermaid source and commit it through the normal review path. That keeps the pull request’s file and the Slack discussion from becoming two silently divergent sources. For a team that maintains the conversation-led board as its working record, link the board version and name who checks it against the implementation.
Check whether the rule improves review
Start with one authoritative diagram: name its owner, write its scope, and add the impact and evidence fields to the pull request path that changes it. After a release or review cycle, inspect a sample of changes that touched documented boundaries and a sample marked “no diagram impact.” Look for missed updates, unnecessary edits, and explanations reviewers could not evaluate. Narrow the trigger if routine changes produce boilerplate; add a specific trigger if meaningful drift passed unnoticed. The aim is a view people can use to make a decision, not a higher completion percentage.
Use an event-based diagram update cadence to decide when a view needs review, and this PR rule to decide what evidence accompanies a particular change.
FAQ
Should every pull request update an architecture diagram?
No. Update a view when a change alters facts within its declared scope. Otherwise, record a short reason when the policy asks for an impact assessment.
Should the rule be part of Scrum’s Definition of Done?
Use the Definition of Done when diagram currency is a quality condition for the Increment. If only a subset of changes can affect a diagram, state the conditional trigger; a PR policy may be clearer for teams that do not use Scrum.
Can CI decide whether architecture changed?
CI can validate declared diagram files, regenerate outputs, and route ownership reviews. It cannot reliably infer from arbitrary code diffs whether a diagram’s conceptual claims are now false.
Does linking an approved diagram mean the implementation matches it?
No. The link shows which design version reviewers considered. A reviewer still needs to compare that view with the code, contracts, or deployed evidence relevant to the diagram’s scope.
What if a design is discussed in Slack but the diagram is maintained in Git?
Link the reviewed Slack version in the PR, export the Mermaid source, and update the repository-owned file in the PR. Keep the repository as the authority for the version that ships.
Add to my Slack