Architecture handoffs that keep the reasoning


Oct 25, 2026 | Read time: 11 mins.

Kevin Donovan · Architects' Hub
​
Forwarded this email? Subscribe to Architects’ Hub for the next issue.

What did you leave in the room?

Hey ,
​
Somebody is about to leave.

A consultant rolls off. A lead architect moves to another program. The person who drew the arrow changes teams.

So we do what most orgs do. We schedule a knowledge transfer session, maybe a handover document, somewhere in the last 10 days.

It lists the systems. It links the diagrams. It names the open decisions. It’s usually accurate.

And 6 months later, the next architect still can’t tell why the nightly batch exists, what the dashed line means, or who retries when Fulfillment times out.

The handover document wasn’t wrong. It just couldn’t see what was missing.

The author is the worst person to spot the gaps, because authors fill them from memory without noticing.

Last week, the drawing was the test. Sketching exposed what you didn’t yet understand.

This week, we turned it around. A reader who wasn’t there exposes what the drawing doesn’t carry.

Today, let’s turn that into something you can run before your next handoff.

In this edition

  • Why “write more documentation” fixes only half of the gaps.
  • 4 kinds of handoff gap, and the different work each needs.
  • The Handoff Check: a 45-minute routine you can copy.
  • A worked example: 5 gaps, and no 30-page handover document.
  • Community Corner.

Let’s get into it.👇

________

🧭

________

​

The page travels. The room doesn’t.

Every architecture artifact is made in a room, physical or virtual.

In that room, everyone knows things the page never says:

  • Which arrows are confirmed and which are still a guess.
  • Why the gray box sits outside this release.
  • That “Platform” means the gateway team, not the cloud team.
  • That the nightly extract stays because the finance close depends on it.

None of that feels like missing information to the people present. They’re not reading the page. They’re remembering the conversation.

Then the page gets forwarded, pasted into a deck, or inherited.

The conversation stays behind.

Monday’s post put it simply: the diagram made sense until it was forwarded. The next team sees an agreed design. You were still checking whether the connection exists.

That isn’t a documentation failure in the usual sense. The diagram may be tidy and current. It just doesn’t say what kind of thing it is, or what the reader can safely do with it.

________

🧭

________

​

4 kinds of gap, 4 different jobs

When a handoff fails, the usual fix is “document it better.”

That helps with some gaps. It does nothing for others.

Classify the gap before you try to close it. I’d sort them into 4 kinds.

1. Context gap

What the reader is missing: what the artifact is. Its purpose, scope, state, and what it can be used for.

What it looks like: someone estimates delivery work from a discovery sketch. Or treats “target state” as committed.

The work: write it down. A few lines beside the artifact are usually enough. Monday’s label covers it: Purpose, State, Use, Next check.

2. Reasoning gap

What the reader is missing: why a choice made sense, and what would make it stop making sense.

What it looks like: the next team either preserves a constraint that no longer applies, or removes one that still matters.

The work: write it down, with a specific shape. Tuesday’s decision fields do this: Purpose, Choice, Accepted downside, Condition, Revisit when. Link the evidence behind the condition.

3. Semantics gap

What the reader is missing: what the symbols and words mean. The dashed line. The color. Which team “Platform” refers to.

What it looks like: a capable reader confidently misreads the page.

The work: sometimes a legend line. Often a conversation. Rene Hjortskov Nielsen made this point earlier this month, and Wednesday built on it: a reader may need someone to explain the symbols before they can challenge the drawing. Decide which one this audience needs.

4. Evidence gap

What the reader is missing: an answer nobody actually has.

What it looks like: the reader asks who retries after a timeout, and the room goes quiet. Or 2 people give different answers.

The work: this isn’t documentation at all. It’s investigation. Check the implementation, the configuration, or the operational evidence. Until then, mark it open and give it an owner.

Here’s the part that matters:

Writing more fixes 2 of these. The other 2 need a conversation or an investigation.

A long handover document can’t solve a semantics gap. It also can’t close an evidence gap. Worse, it can make an evidence gap look settled, because a confident sentence reads like a fact.

Sorting the gaps tells you which work to do. It also tells you who needs to do it. The author can close context and reasoning gaps alone. Semantics gaps need the reader. Evidence gaps usually need the owner of the system.

Why you can’t find these gaps alone

You can review your own diagram 10 times and miss all 4.

Your memory completes every sentence. You read “retry” and silently add “Order owns it, with the original idempotency key.” The page never said that.

That’s why Wednesday’s test uses another person. Give them a task, not a review.

“Does this make sense?” invites a polite yes.

“Show me where the failed order waits” shows you exactly where the page stops working.

And Thursday’s failure walk makes it sharper. Happy paths tend to be drawn well. The questions that hurt sit on the failure path: who acts, what state the system is in, and what stops a retry from doing the work twice.

​Jordan Corn suggested explaining what happens along the arrows during the previous week’s drawing exercise. A failure walk checks whether that explanation made it onto the page.

One caution I’d keep in view. A smooth walkthrough doesn’t prove the system behaves that way. It proves the artifact and the reader agree. Behavior still needs checking against the implementation and operational evidence.

________

🧭

________

​

The Handoff Check

Here’s the routine. It takes about 45 minutes, split across 3 parts. The fields are stacked so you can copy them into a note, a wiki page, or an email.

Which artifact first?

Don’t start with everything. Pick 1 artifact that meets at least 2 of these:

✅ A team still makes decisions from it.

✅ It sits on a failure or recovery path.

✅ Its author or owner is leaving, rotating, or stretched thin in the next 3 months.

✅ It gets forwarded to people outside the team that made it.

Part 1: Prepare the artifact (10 minutes, you alone)

Add a label beside the artifact. Put it where someone copying the image or page will see it.

Purpose:​
What question was this made to answer?

State:​
Working hypothesis, reviewed, or agreed? What remains unconfirmed?

Use:​
What can a reader safely do with it? What should they not do with it yet?

Next check:​
What needs confirming, and with whom?

Maintained source and owner:​
Where does the current version live, and who corrects it?

Then pick the 1 to 3 decisions the artifact depends on most. For each, check that a reader can find:

Choice:​
What did we decide?

Accepted downside:​
What are we carrying because of it, and who accepted that?

Condition:​
What current fact makes this choice reasonable? Link the evidence.

Revisit when:​
What change would make it worth reopening?

If you have to explain any of these from memory, that’s your first gap. Write it down now.

Part 2: Let a reader try (20 minutes, with someone who wasn’t there)

Choose a reader close to the real next user. A support engineer for a recovery flow. An incoming architect for a platform decision. A funding owner for a roadmap.

Give them the artifact and 3 tasks. Adapt these:

Task 1: Find where [a failed item] waits.

Task 2: Tell me who takes the next action.

Task 3: Show me which source establishes the current state.

Then walk 1 failure through it. Keep it to 1:

Failure:​
Describe a specific failure. For example: payment authorized, call to Fulfillment times out, order still pending.

Ask:​
What happens next? Who checks? Who acts? What prevents a duplicate effect?

Your rules while they work:

→ Don’t point.

→ Don’t explain unless they’re stuck for more than a minute.

→ Write down every place they guess, stop, or ask.

You’re testing the artifact. You’re not testing the colleague. Say that out loud at the start.

Part 3: Sort and route the gaps (15 minutes, you alone)

For every place the reader needed help, copy this block:

Where they stopped:​
What were they trying to do?

Gap type:​
Context, Reasoning, Semantics, or Evidence.

Next work:​
Add a sentence, add a legend, book a walkthrough, or open an investigation.

Who:​
Who can close it? For Evidence gaps, usually the system owner.

By when:​
A date, not “soon.”

Then make 1 rule stick: an Evidence gap stays visibly open on the artifact until someone closes it. Don’t let it disappear into a ticket nobody links to.

That’s it. You’ll usually end up with a short list. Most items take minutes. One or two take real work, and now you know which ones.

________

🧭

________

​

A worked example: 5 gaps, no 30-page document

Let’s run it on a fictional handoff. The names and details are illustrative, not a client story.

Priya is the architect for an order recovery flow across Order, Payment, and Fulfillment. She moves to another program in 6 weeks. Tom, a senior engineer from the support side, will own the architecture after that.

Priya picks 2 artifacts: the recovery-flow diagram and the decision record “Use the nightly extract for reconciliation.” Both pass the “which artifact first” test. Teams still decide from them, they sit on a recovery path, and their author is leaving.

She spends 10 minutes on Part 1. Then Tom spends 20 minutes with the artifacts. Here’s what came out.

1. Tom treats the diagram as agreed

What happened: The header says “Order recovery, target.” Tom asks whether the gray box is in scope for the next release.

Gap type: Context.

Next work: Priya adds the label. State: reviewed with Order and Payments, retry ownership unconfirmed. Use: basis for discussion, not yet for implementation. The gray box is marked out of scope for this release.

2. Tom reads the dashed line as an event

What happened: He traces order data to the warehouse along the dashed line and calls it the event feed. It’s the nightly extract.

Gap type: Semantics.

Next work: A 1-line legend fixes this for Tom. The support team will also use the diagram, so Priya books a 30-minute walkthrough with them before she leaves.

3. Tom asks why the batch still exists

What happened: The decision record is accurate. It doesn’t say the finance close depends on a completeness check the event path doesn’t provide yet. Priya explains it from memory.

Gap type: Reasoning.

Next work: Priya adds the accepted downside (delayed reconciliation, another job to run), the condition, and the revisit trigger: Finance and the service owner verify an alternative meets the check. She links the finance reconciliation requirement.

4. Nobody knows who retries after a timeout

What happened: On the failure walk, Tom asks what happens when the call to Fulfillment times out. The diagram says “retry.” Priya believes Order retries with the original idempotency key. She isn’t sure Fulfillment ignores the duplicate.

Gap type: Evidence.

Next work: Not a documentation fix. Priya marks the arrow as unconfirmed and asks the Fulfillment lead to confirm how the implementation handles duplicates. Owner: Fulfillment lead. Date: before Priya leaves.

5. Tom asks who updates the diagram

What happened: The diagram lives in Priya’s personal folder. Her name is the only one on it.

Gap type: Context.

Next work: Move it to the team space. Name Tom as the owner as of her last day. Add “Maintained source and owner” to the label.

Total: 3 sentences of text, 1 legend line, 1 walkthrough, 1 investigation, and a file move.

Notice what didn’t happen. Nobody wrote a 30-page handover document. And the most important item, the retry question, would likely have survived any document, because Priya believed she knew the answer.

________

🧭

________

​

The record has 2 jobs

​Anders W. Tell corrected the previous week’s discussion that shaped Friday’s post: diagrams carry knowledge between people and across time.

​Grant Ecker added the other half: the document is an output of collaboration.

Put those together and a usable record has 2 jobs.

It should carry enough context for someone to understand the choice.

It should carry enough uncertainty for someone to challenge it.

Most handover material does the first and quietly drops the second. It reads as settled. That’s the version that gets estimated from, built on, and defended long after the condition behind it changed.

Keep the question marks. Keep the reason. Give the reader a route to the person who corrects it.

________

🧭

________

​

🧭 Community Corner

3 contributions from this week's conversations that are keepers:

​Robert Coster uses different shapes and fonts for what’s definitive, what’s in flux, and what needs research. A practical way to make uncertainty visible inside the drawing, wherever it gets forwarded.

​Jordan Corn shared a contact-center example. Calls were failing, and people had different explanations. Mapping the flow surprised everyone with what they learned about the failure cases. They documented it and came away with work to do.

​Dan McDaniel challenged the value of recording past reasoning from a boardroom perspective. He hears requests to reach the next target, and worries about bureaucracy. Fair challenge. I’d keep only the history that helps someone make or revisit a decision. That gives the record a job to earn its upkeep.

Thank you to everyone who added to the discussion this week.

________

🧭

________

​

Try it before your next handoff

You don’t need someone to resign to run this.

Pick 1 artifact a team still decides from. Give it a label. Check the reason behind its biggest decision.

Then hand it to someone who wasn’t in the room, give them 1 task and 1 failure, and stay quiet.

Sort what you hear into Context, Reasoning, Semantics, and Evidence. Write the first 2. Book the third. Investigate the fourth.

Hit reply and tell me: which kind of gap did your reader find first?

I’d like to know which one shows up most often.

Until next Sunday,

Kevin

________

________

Kevin Donovan​
I write Architects' Hub every Sunday for senior architects and technology leaders.
You're getting this because you subscribed at architects-hub.kit.com.
Know someone who’d find this useful? Forward it to them.

​

Korsvejen 9, Viborg, Viborg 8800
​Unsubscribe · Preferences​

Architects' Hub

A Sunday newsletter for senior and enterprise architects. One decision, one practical model, one tool you can use Monday. Written by Kevin Donovan. Join 2,500+ architects. One email every Sunday.

Read more from Architects' Hub
Three doors slightly ajar in a row. Through them, a telephone, a stack of documents with a magnifying glass, and an arrow curving back on itself. A single coin rests on the floor in front of the doors.

Nov. 22 2026 | Read time: 11 mins. Kevin Donovan · Architects' HubForwarded this email? Subscribe to Architects’ Hub for the next issue. The room went quiet Hey , Two Sundays ago, our hypothetical pilot case got its commitment record. Last Sunday it got a walkthrough, and the operating owner signed with 3 tests on record. The AI assistant now drafts delayed-order replies for 3 teams, and the drafts are good. This week someone proposed letting it do more than just draft… In this edition The...

Five simple figures in a ring around a small central box, each holding one object: a magnifying glass, a signpost, a wrench, a mop, a headset. One figure carries a leaning stack of boxes.

Nov 15, 2026 | Read time: 11 mins. Kevin Donovan · Architects' HubForwarded this email? Subscribe to Architects’ Hub for the next issue. Tuesday, 10:40 am. Hey ,Last Sunday we left a hypothetical customer-service assistant with a commitment record and unanswered questions about capacity, data and support. This week, move the story forward 3 weeks. The team has agreed to a bounded trial on 1 queue. Agents still review every draft. Wider rollout is waiting. I want to spend this edition with the...

A working terminal with four loose connections labeled Funding, Operations, Data and Authority.

November 8, 2026 | Read time: 9 mins. Kevin Donovan · Architects' HubForwarded this email? Subscribe to Architects’ Hub for the next issue. Hey ,In this edition of Architects' Hub: What the service lead heard when the sponsor said, “We should roll this out.” A commitment record filled in for one example customer-service queue, PLUS a blank copy for yours. How to take a conditional decision back to the sponsor who wants a date. Community Corner: Santiago Jesus Lasso Valenciano on the work that...