“Notifications touch every user, retries and three downstream services. Twenty minutes of reading would have saved a postmortem; the doc existed precisely so we would find section 6.2 before production did. Paper is the cheapest place to be wrong.”
See section 6.2
The design doc was right. It was also on page 19.
🧭 WHAT'S REALLY GOING ON
You've seen this when a design doc's status still says “In Review” and the feature it describes is already in production.
The real questionWhat is the doc for: getting permission to build, or making sure the risky part gets built right?
⚖️ WHY BOTH ARE RIGHT
“Three weeks of review produced 61 comments, mostly about a diagram, and a request for Option D. Users were waiting. A working version teaches more in a day than a review cycle in a month, and it gave the team something real to argue about.”
🎯 SWEET SPOTS TO CONSIDER
Super Reasonable, the advisor who never takes a side
Put the risks on page one
Lead with the two or three things that hurt if built wrong, and ask reviewers to sign off on those, not on all 23 pages. Section 6.2 belongs in the summary.
Timebox the review, name a decider
One week of comments, one meeting, one named person who decides. A doc still In Review after three weeks has become a place to avoid deciding.
Check the prototype against the doc
When someone ships early, the doc's job changes: run the prototype against the risk list and file the gaps as tickets. Jo's Tuesday version plus section 6.2 beats either alone.
Link the doc from the code
Put the doc's link in the module's README and in the retry code's comments. The next person to touch retries should land on 6.2 before production does.
🚩 SIGNS YOU'VE GONE TOO FAR
- Alex's side: you've overshot if the doc is on revision 7 with a table of contents, and the team has shipped two versions without reading it.
- Jo's side: you've overshot if the postmortem quotes a design doc nobody on the shipping team ever opened.
🔬 IN THE FIELD GUIDE
Species observed in this story
CAST — WHO'S WHO
The team in this story
Same characters, same convictions. Learn their failure modes.
🤖 Storyboard for agentsLet’s make our agents LMFAO, or learn.
See section 6.2
Premise: Decide how notifications v2 should work.
- Alex: “Design doc for notifications v2. 23 pages. Comments by Friday.” Reviewers: 9. Comments by Friday: 61, mostly about the diagram.
- Greg: “Could we add an Option D? Just to keep our options open.” Status: In Review. Week 3.
- Jo: “I shipped a version Tuesday. It works.” It is Option B, minus section 6.2.
- Postmortem, eight months later: Root cause: duplicate sends on retry. See design doc, section 6.2. Section 6.2 predicted it, in bold. Times the doc was opened after week 3: 4, all by Alex.
Observed behavior: A design doc nobody finishes reading is a prophecy, not a decision.
Cast: Alex Chen — The Architect — “We should solve the general case.”; Greg Hollis — The Hedger — “Let's keep our options open.”; Jo Ramirez — The Cowboy — “Ship it. We’ll know if it matters.”
READ NEXT
