Architecture Notes That Drift: How ERP and CRM Customizations Outpace Their Own Documentation

Deck: When a configuration decision lives only in one consultant's memory, the next question about it costs the whole team a day.

What this article solves

Architecture notes for ERP and CRM implementations go stale because they are written once and never connected to the tickets, PRs, or calls that change them. This post explains how to build a traceability workflow that keeps customization documentation current from the first design decision through client handoff.

Who this is for: Tech leads and ICs on ERP or CRM delivery teams, and the delivery PMO stakeholders who need evidence tied to what actually shipped.

The status report landed in the #project-alpha-delivery channel at 8:47 on a Thursday morning. The client's ops director wanted one thing: written evidence that the custom approval workflow in their new CRM matched the design that had been signed off in week three of discovery. Go-live was nine days away.

The delivery PMO lead pulled up Confluence. The design doc was there, dated six weeks back, with a clean diagram and three bullet points about routing logic. But the implementation had moved. Two change requests had come through Linear since that doc was written. A consultant who had since rolled off the engagement had made the calls on both. The reasoning was not in Confluence. It was not in the ticket comments. It was, as far as anyone could tell, in that consultant's head.

The PMO lead spent the next four hours reconstructing a decision that had already been made, approved, and built.

The gap between design and delivery

Architecture notes for ERP and CRM customizations fail for a specific reason: they are authored at the point of design, not updated at the point of change. The Confluence page or Word doc captures the intent at week three. The implementation reflects week eleven. Nothing connects them.

This is not a discipline problem. Consultants are not ignoring documentation out of laziness. They are closing tickets, responding to client questions, and moving to the next sprint. Stopping to update a design doc that lives in a separate tool, under a different login, with no link back to the ticket that triggered the change, is a context switch that compounds across every decision in a delivery.

The result is a Confluence design that describes a system that no longer exists, and a codebase that reflects decisions nobody wrote down.

Why ERP and CRM customizations are especially vulnerable

Standard software projects have at least one forcing function for documentation: the PR review. Someone has to approve the change before it merges, and that review creates a natural moment to record the reasoning.

ERP and CRM customizations often bypass this. Configuration changes happen inside the platform itself, not in a file diff. A Salesforce flow, a SAP pricing condition, a Dynamics business rule: these ship through the admin interface, not through GitHub. There is no PR. There is no required reviewer. There is no artifact that captures what changed and why.

When a change request comes in late in the engagement, a senior consultant makes a judgment call, implements it the same afternoon, and closes the ticket. The ticket says "completed." It does not say why the routing logic was changed to skip the regional manager tier, or what the client signed off on, or whether that decision affects the integration with the legacy billing system.

Six weeks later, the ops director asks for evidence. The PMO lead opens Confluence.

Traceability as a review discipline

The fix is not a better template. It is connecting the artifact to its source at the moment the decision is made.

Every configuration decision in an ERP or CRM delivery has a paper trail. The change was requested somewhere, discussed somewhere, and approved somewhere. A ticket in Jira or Linear. A message in a Slack channel. A call recorded in Fathom. A requirement in a Google Drive spec. The decision did not appear from nowhere.

The discipline is linking the architecture note to that source at the time of implementation, not retroactively. When a consultant closes a ticket that changes the approval workflow, the architecture note for that workflow should be updated with a direct reference to the ticket number, the date, and the name of whoever approved the change. One sentence. One link. Done before the ticket closes.

This makes the architecture note a living record rather than a historical snapshot. It also makes the review workflow tractable. A tech lead reviewing a configuration change can check the note, see the linked ticket, and confirm the reasoning without asking the consultant who made the call.

ScopeDocs is built around exactly this: every decision from a discovery call, requirement, ticket, or approved change becomes a source-linked delivery record, so the next consultant who touches that configuration does not spend four hours reconstructing what was already known.

In practice

Consider a mid-engagement change on a Dynamics 365 implementation. The client's finance team requests that the custom invoice approval threshold be raised from $10,000 to $25,000 for a specific business unit. The consultant handles it in an afternoon. The ticket in Jira, PROJ-1142, is marked done.

Without a traceability workflow, the architecture note for the invoice approval module still reads "$10,000 threshold, all business units." The next consultant to touch that module sees a discrepancy between the note and the configuration. They raise it in the next standup. The PMO lead checks the Confluence page, finds no update, and asks the original consultant, who has since rolled to another client.

With a traceability workflow, closing PROJ-1142 triggers an update to the architecture note: "Threshold raised to $25,000 for BU-West per client approval, PROJ-1142, 14 March." The note links to the ticket. The ticket links to the client email thread. The PMO lead's status report takes ten minutes, not four hours.

Checklist: keeping architecture notes in sync with your ERP or CRM codebase

Every architecture note references the ticket or requirement that created it
Change requests trigger a note update before the ticket closes, not after
Configuration changes made inside the platform (not via PR) have a corresponding log entry with a linked source
Client approvals are captured as a reference in the note, not just in email
Rolled-off consultants hand off open note updates as part of transition
The PMO lead can pull evidence for any configuration decision without asking a consultant
Architecture notes are reviewed at each sprint close, not only at go-live

Related ScopeDocs resources

The decision was made. The ticket was closed. The implementation was correct. The only thing missing was a single sentence connecting the change to its source, written at the moment it happened. That sentence is the difference between a four-hour reconstruction and a ten-minute status report. ScopeDocs exists to make that sentence automatic.