If your architecture doesn't tell a story,
who will listen?

Every system I've inherited that people called 'a mess' had a working system underneath the mess. What was actually missing was a story anyone could repeat back accurately six months later. If the code wasn't the problem, what was, and why does a perfectly functional system keep getting rewritten anyway?

01  ·  Correct isn't the same as understood

An architecture can be technically sound and still lose the room the first time someone asks 'why does it work this way,' and the honest answer is three engineers' worth of tribal memory that never got written down. The system is fine. The account of it is missing, and eventually the account is all anyone outside the team actually has.

The gap between 'it works' and 'I can explain why it works, to someone who wasn't there' is where most of a system's political risk quietly lives.

02  ·  The story that fills the vacuum is rarely accurate

When nobody can explain why a system looks the way it does, the explanation that survives is whoever's loudest guess sounded most confident in the postmortem. 'Legacy cruft.' 'Nobody thought this through.' 'We should just rewrite it.' None of those are usually true. All of them are cheaper to say than the real, slightly boring reason a decision made sense at the time and still does.

$ postmortem trace-narrative --incident=inc-3390
repeated narrative in standup: "legacy cruft, nobody planned this"
actual decision record, 2023-11: sharding was rejected because the
  write volume didn't justify it at the time, revisit at 5x traffic
current traffic: 4.2x baseline — the constraint hasn't changed yet
# the narrative that survived was wrong. the record that would have
# corrected it existed. nobody read it before the standup.

03  ·  What a story actually requires

Not a diagram. Diagrams show structure, not reasoning. A story needs the decision, the alternative that was rejected, and the constraint that made the rejection correct at the time. Those three things, repeated consistently, are what let someone six months removed defend a choice they didn't make.

1. 01Record the rejected alternative, not just the choice. What you didn't build tells the next engineer more than what you did — it's the part that stops them from re-litigating a settled question.
2. 02Name the constraint, not just the decision. "We chose X" expires the moment someone disagrees with X. "We chose X because Y was true" survives until Y changes.
3. 03Write it where the next engineer will actually look. A decision record buried in a wiki nobody opens might as well not exist. Put it next to the code it explains.
4. 04Update it when the constraint changes, not just when you remember to. A stale rationale is worse than no rationale — it actively defends a decision that no longer makes sense.

04  ·  This is a leadership job, not a documentation task

Handing this to whoever has spare time treats it as busywork instead of what it is: the difference between a system that survives its original team leaving and one that gets quietly rewritten by someone who never understood what it was protecting against. A system that can't tell its own story gets a new one written for it, and you don't get to pick the author.