From Whiteboard to Model: Capturing Architecture Decisions as They Happen

A decision gets made at 3:47 on a Tuesday afternoon. Someone says "let's put a queue between the order service and the fulfilment system instead of calling it synchronously," three other people nod, someone sketches a box and an arrow on the whiteboard, and the meeting moves on to the next agenda item. By Thursday the whiteboard has been wiped for someone else's retro. By the following Tuesday, the person who was supposed to "update the architecture" has updated four other things instead, because updating the architecture was never actually on their calendar — it was a mental note attached to an already full week.

This is not a story about a lazy team or a broken process. It's the default outcome of how architecture decisions are made almost everywhere: verbally, informally, in a room or a call, at the moment someone needed to decide something so the work could continue. The decision itself is usually fine. What fails, reliably, is the six inches between the decision and the record of it.

The decision happens once — the record has to catch up

Architecture decisions are made in real time, under the pressure of whatever problem prompted them. A team is blocked on a design question, someone proposes an answer, the room agrees, and everyone goes back to what they were doing. That's the entire lifecycle of the decision itself — it takes minutes, sometimes seconds once the discussion has run its course.

The record of that decision is a separate act, performed later, by someone who has to reconstruct what was decided from a memory that's already competing with everything that happened since. And "later" is doing a lot of work in that sentence. Later might be an hour, if the person is diligent and the meeting was short. More often it's whenever there's a gap — end of day, end of sprint, the week after, or never, because there was always something more urgent between the decision and the record.

Three things typically happen to a decision made this way, and none of them are good:

• It's never written down anywhere. It lives in the memory of the people who were in the room, degrades the way memory does, and eventually only survives as an assumption someone makes without being able to say where it came from.
• It's written down days later, from memory, already slightly wrong. The queue example above becomes "we're using async messaging somewhere between order and fulfilment" — true in spirit, wrong in the specific detail that would actually matter to the next person reading it, like which side owns the queue or whether it's one queue or two.
• It's written down accurately, but only as prose — an ADR, a meeting note, a Confluence page — and never becomes a structural change anywhere the architecture is actually modelled. This one is the most deceptive, because it looks like the process worked. The decision has a paper trail. It just isn't connected to anything that gets validated, queried, or drawn on again.

All three failure modes share a root cause: the record was treated as a separate task from the decision, to be done afterward, by someone, at some point. Separate tasks compete with the rest of the backlog. They lose more often than anyone wants to admit.

Why "update the architecture" loses to the backlog

It's worth being honest about why this keeps happening, because the usual answer — "the team needs to be more disciplined" — is both true and useless. Nobody has ever fixed a systemic scheduling problem by asking people to care more.

"Update the architecture" loses to the backlog for structural reasons, not motivational ones:

• It has no natural deadline. A ticket with a sprint attached gets worked. A vague obligation to "reflect the queue decision in the architecture at some point" has no forcing function, so it slides against anything that does.
• It's disconnected from the moment of highest knowledge. Right after the decision, everyone in the room knows exactly what was agreed — which system owns the queue, what the retry semantics are, why synchronous calling was rejected. A week later, that detail has to be reconstructed, which is slower and less accurate, which makes the task even less appealing to start.
• It usually requires a tool-switch and a "proper" pass. If updating the architecture means opening a heavyweight modelling tool, picking the correct ArchiMate element types, getting the relationship semantics exactly right, and producing something presentable — that's a real chunk of work, not a two-minute update. Faced with a small decision and a disproportionately heavy way to record it, most people quite reasonably decide it can wait. It waits indefinitely.
• Nobody owns it specifically. "Someone should update the model" is not the same as a name and a deadline. Diffuse responsibility is a well-documented way for a task to never get done, and architecture updates are a textbook case.

Put together, these four points describe a task that is unscheduled, gets harder the longer it's delayed, is disproportionately effortful relative to the decision it's recording, and belongs to nobody in particular. That combination doesn't need bad intentions to fail. It fails by default, every time, unless something changes about when and how the capture happens.

Close the gap, not the ceremony

The fix that actually works isn't a better reminder system or a stricter process document. It's shrinking the distance between the decision and the record until there's no gap left for the backlog to win in — capturing the decision as a real model change, in the same session it was made, using whichever input mode happens to be fastest at that moment.

That last part matters as much as the timing. "Capture it immediately" only works if capturing it is actually fast, which means it has to fit the moment rather than force a specific workflow onto every situation. Sometimes the fastest path is dragging two boxes and a line on a shared canvas while the room is still looking at it. Sometimes everyone's already walking out and the fastest path is describing the decision in a sentence to an AI assistant on the way to the next meeting, then reviewing what it proposes. Neither is more legitimate than the other — both produce the same thing, which is a change to the actual model, not a note about one.

Capturing it live, on the spot

If the discussion is already happening around a shared screen — which it increasingly is, even for in-person meetings — the fastest way to record "queue between order and fulfilment, order service publishes, fulfilment consumes" is to drag a queue element onto the canvas, connect the two existing services to it, and remove the direct call. That's three or four actions, done in under a minute, while the exact shape of the decision is still fresh enough that nobody needs to explain it to the person capturing it. The room is already looking at the same picture; the picture is now also the record.

What makes that fast enough to do while a discussion is still running is that the canvas is editing the model directly, not a drawing of it. Dropping a queue element onto the view creates a real element with a stable identity, and connecting it to the order service creates a real relationship — the same objects any query, any rule check, and any other view will see a moment later. There's no separate "commit this sketch to the model" step to forget, and no window in which the picture on the screen and the model underneath disagree with each other. If the element already exists somewhere else in the portfolio, the canvas offers the existing one rather than making a near-duplicate with the same name, which is the single most common way in-meeting capture quietly poisons a model in tools that treat a diagram as a canvas of shapes.

It also means the feedback arrives while the room is still assembled. If the new relationship trips an architecture rule — a queue with no declared owner, a dependency crossing a zone boundary that requires sign-off — that shows up as a flag on the element immediately, and the three people who could answer the question are still standing there. Ten seconds of "who owns this queue, then?" in the meeting is worth more than a governance finding raised four months later against a decision nobody remembers making.

Capturing it right after, through conversation

Not every decision happens in front of a canvas, and not every architect wants to be the one operating a tool live while also participating in a discussion. For those cases, the fastest path is describing what was decided, in plain language, to an AI assistant right after the meeting ends — "we agreed to put a queue between the order service and fulfilment, order publishes, fulfilment consumes, replacing the direct synchronous call." The assistant proposes a structured change: a new queue element, two relationships, one relationship removed, with a short explanation of how it read the request.

Nothing is applied automatically. What comes back is a ModelPatch — a concrete, reviewable diff against the real model, not a paragraph of text pretending to be documentation. The architect reads it, checks that it matches what was actually agreed, and either approves it as-is or adjusts it first. The whole exchange takes less time than it would have taken to open a ticket asking someone to "update the architecture later."

Rough is fine — the case for the Generic profile first

A large part of why "update the architecture" turns into a heavy task is the assumption that updating it means doing it properly: the correct ArchiMate layer, the correct element type out of a list of forty, a relationship that satisfies the metamodel's rules about what can connect to what. That's a reasonable bar for a published, reviewed architecture view. It's a terrible bar for capturing a decision that was made in ninety seconds during a status meeting.

This is exactly the gap a lightweight Generic profile is meant to close. It doesn't ask anyone to decide whether the queue is an Application Component or a Technology Node, or whether the relationship is a Flow or a Serving relationship, before it will let them record that a queue exists between two services. It lets the decision go in as what it actually is at that moment — a box, a box, and a line between them, with a short label — and defers the methodological correctness to whenever someone does a proper pass, if one is ever needed.

That ordering matters more than it looks. Requiring the formal profile up front doesn't produce more rigorous architecture; in practice it produces fewer captured decisions, because the friction of getting the classification right at the moment of capture is exactly the kind of friction that sends the task back to the backlog. A rough element in the Generic profile that exists is worth more than a perfectly typed ArchiMate element that never gets created because nobody had time to get it right in the room. And because the profile is pluggable rather than fixed, nothing about capturing it loosely today prevents reclassifying it properly — as an Application Service, a Technology Node, whatever fits — once there's time to do that pass without it being the bottleneck on recording the decision at all.

ADRs still matter — for the why, not the what

None of this is an argument against architecture decision records. A well-written ADR captures something a model genuinely can't: the reasoning. Why a synchronous call was rejected, what alternatives were considered, what tradeoff the team accepted, who pushed back and why they were overruled. That's real institutional memory, and prose is the right medium for it — nobody wants to query a graph to find out why a decision was made, they want to read a paragraph that explains it.

The problem isn't that ADRs exist. It's that in a lot of organizations, the ADR is the only artifact the decision produces — and prose, however well written, doesn't do the things a model does. An ADR doesn't get validated against a rule like "every queue must have a documented consumer." It doesn't show up when someone runs impact analysis on the fulfilment system six months later. It doesn't stay in sync with the diagram someone draws for the next stakeholder review, because nothing connects the two — the diagram gets updated, or doesn't, entirely independently of whether the ADR was written. A folder full of accurate, well-reasoned ADRs can coexist for years with an architecture model that has quietly drifted away from every one of them, because nothing ever forced the two to agree.

The two aren't competitors. An ADR that explains why the queue was introduced, sitting next to a model that actually contains the queue as a real, connected element, is a better record than either one alone — and produced with barely more effort, since the model patch itself takes minutes and the ADR can even reference the specific elements the patch created. What doesn't work is treating the ADR as a substitute for the structural change, on the assumption that writing the decision down in prose is equivalent to recording it. It isn't. One is a memory of a decision; the other is the decision, made durable and checkable.

What captured actually buys you

It's worth being specific about what changes once a decision becomes a real model change within the same session, rather than a note waiting to be transcribed.

• It gets validated immediately, not eventually. If the new queue relationship violates a rule — say, a governance rule that anything crossing a security boundary needs an owner tagged — that shows up the moment the change is proposed, while the context to fix it is still in everyone's head, not months later during an audit.
• It's queryable the next time someone needs it. The next person asking "what talks to fulfilment" gets the queue in the answer, automatically, because it's a real relationship in the model rather than a sentence in a document nobody thought to search.
• It shows up in every view that should show it, without a second pass. Because a view is a query over the model rather than a hand-maintained picture, the queue appears in the integration view, the security view, and the landscape view the moment it exists — nobody has to remember to add it to each one separately.
• It's attributable and timestamped. The change carries who made it and when, in the same way any other version-controlled artifact does, which is a far better audit trail than "we think this was decided sometime in Q2."
• It's cheap to correct. Because the capture happened close to the decision, correcting a small mistake in it is also close to the decision — a quick fix, not an archaeology project reconstructing what was actually agreed three months ago.

A worked scenario

Picture a slightly larger version of the queue example — a planning session where the team decides to split a monolithic "Orders" application into a thin API layer and a separate fulfilment worker, because the batch processing was starting to block the interactive request path. The discussion covers real ground: what the new boundary is, which team owns which side, what happens to the existing database, whether there's a transition period where both pieces still share it.

In the old pattern, this produces a meeting note, maybe an ADR if someone's disciplined about it, and a mental note to "split this properly in the architecture tool at some point." Three weeks later, when someone actually opens the tool, they're reconstructing a decision that had five moving parts from a note that captured maybe two of them clearly. The database-sharing detail — the part most likely to actually bite someone during the transition — is the part most likely to have been glossed over in the note, because it felt like an implementation detail at the time rather than an architectural one.

Captured in the session instead, the shape is different. While the discussion is still live, someone splits the Orders element into two on the shared canvas, draws the interim shared-database relationship explicitly with a note that it's transitional, and connects each new piece to its owning team. It's rough — nobody's arguing about whether the API layer is technically an Application Component or an Application Interface, it just goes in as a Generic-profile element for now. Right after the meeting, the same person describes the transitional detail to the AI assistant to make sure the temporary shared-database relationship is tagged as temporary with a target removal date, reviews the proposed patch against what was actually agreed, and approves it. Ten minutes of total effort, done, while every detail was still fresh — including the one that would have been the first thing forgotten.

Three weeks later, when someone does look at this properly — reclassifying elements into the correct ArchiMate types, tidying the layout for a stakeholder presentation — they're refining an accurate rough model, not reconstructing a decision from a note that only captured half of it. That's a meaningfully easier task, and one that's far more likely to actually get scheduled, because it's polish rather than recovery.

Objections worth taking seriously

"Doesn't this slow the meeting down?"

Dragging two boxes takes less time than the sentence used to describe the decision out loud. The AI-assisted path is designed for exactly the case where doing it live isn't practical — it moves the capture to immediately after, not into the meeting itself, and reviewing a proposed patch takes less time than writing the equivalent paragraph in a document from scratch. The comparison that matters isn't "capturing it live" versus "not capturing it at all" in terms of meeting time — it's ninety seconds now versus an open-ended task that, empirically, tends to cost far more than ninety seconds whenever it does eventually get done, and frequently costs infinitely more by never getting done at all.

"Won't rough, in-session captures be wrong sometimes?"

Sometimes, yes — a detail gets missed, a relationship direction gets drawn backwards, an AI-proposed patch mischaracterizes something and needs correcting before it's approved. That's a real cost, but it's a much smaller one than the alternative failure mode, which isn't "occasionally wrong in a small way" but "not there at all, or wrong in a way nobody catches until it matters." A rough model that's captured immediately and reviewed before being applied is self-correcting in a way a note written from memory three weeks later simply isn't — there's no review step for a memory. And because every AI-proposed change here is a patch a human approves rather than an automatic edit, the review step that catches those mistakes is already built into the workflow, not an extra step someone has to remember to add.

"Isn't this just moving the same work earlier, not eliminating it?"

Partly true, and that's the point. The work of recording the decision has to happen somewhere; the argument here is about when, not whether. Doing it while the decision is still fresh, using whichever mode is fastest, and against a profile that doesn't demand premature precision, is genuinely less total work than doing it later — because later requires reconstruction, and reconstruction is more expensive than transcription. It also happens to be the version of the work that a busy person is actually likely to do, which the theoretically-equivalent-but-deferred version of the task frequently isn't.

The habit worth building

None of this requires a new process document or a mandate from above. It requires one habit: when an architecture decision gets made, whoever's in the room reaches for whichever of the two capture modes is faster right then — the canvas if it's already open on the shared screen, or a short description to an AI assistant reviewed a minute later if it isn't — and treats that as part of making the decision, not as a follow-up to it. The Generic profile means nobody has to get the taxonomy right before they're allowed to record what happened. The review step on every AI-proposed patch means speed doesn't come at the cost of an unreviewed model. And the ADR, written afterward with as much care as ever, captures the why next to a model that already, accurately, captures the what.

The whiteboard was never the problem. It's a fine place to think out loud, and it always will be. The problem was always the six inches between the whiteboard and anything that survives past Thursday. Closing that gap is not a bigger job than writing a note later — it's a smaller one, done at the only moment when everyone in the room already knows exactly what was decided. Mooodels is built around making that moment the place the record actually gets made, in whichever mode is fastest, rather than a separate task competing with everything else on someone's list.