Your design doc runs 4,000 words and took most of a week. You paste the link into the channel with "can you look at this when you get a chance?" and wait.
Two things come back, and both are failures. One is LGTM ninety seconds later — nobody read it, and you hold a rubber stamp you will cite in six months when the thing breaks. The other reopens the queue-versus-cron question you settled in week one, because nothing in 4,000 words said it was settled.
The pull request version has the same shape: the description explains what changed, not what was considered and rejected. The reviewer can trust you or re-derive your first two days.
Four things fix most of this, and none need a tool.
Three different asks share the word "review"
Correctness. Does the retry path terminate, does the index cover the query you think it covers, does the failover hold under partition? Needs someone who knows the system, and real time: an hour, not a coffee break.
Approach. Is this the right shape of solution at all, before anyone implements it? Needs judgment and scope context more than deep system knowledge, often takes twenty minutes, and the legitimate answers include "don't build this."
Blessing to proceed. You are confident it is right and need whoever owns the area not to be surprised in two weeks. A five-minute ask, and saying so spares everyone the guessing.
Most review frustration is a mismatch — you wanted approach feedback and got line-by-line correctness on a design you may not ship. Naming the one you want costs a sentence: "approach feedback, not line-by-line; I'll come back for correctness once the shape is agreed."
Rejected alternatives are the expensive thing to leave out
Reviewing means generating alternatives. That is the job. If your doc omits the ones you already killed, a good reviewer spends their whole budget regenerating them, and you read the result as inattention. They were paying attention. You never told them where you had been.
One line each — the option, and the specific reason it lost:
- Postgres
LISTEN/NOTIFY— has to survive a deploy; notifications drop on disconnect. - Cron plus a status column — fine now, breaks at the volume we are sizing for.
- The vendor queue — rejected on cost, not capability.
The reviewer can accept each reason or attack it, and the attack is what you want. "Notifications dropping doesn't matter here, because…" beats any approval.
Include the one you rejected because you ran out of time to evaluate it, and say so. It is the likeliest to be worth reopening, and the one people omit because it looks like laziness. On the page it reads as honesty.
Separate what is decided from what is open
A design doc reads flat. Every sentence looks equally negotiable, so a reviewer engages with whichever paragraph they have an opinion about — possibly the one you closed a month ago. Split it explicitly:
- Decided: we stay on the existing broker, because ops already runs it. Reopen if you know of a plan to retire it.
- Open: whether writes go through the same path or get their own. I genuinely do not know.
The reopener clause is what makes this safe. "Decided" with no condition attached is a wall, and walls get respected by the people you least want to silence — the ones who think the framing itself is wrong. Say so explicitly: if this is the wrong problem to solve, that is in scope. Otherwise a tidy list of settled questions buys a quiet review and a bad design.
Say what happens if nobody answers
Silence is not consent, and it is not a stop either. Name the default: "I am merging the migration branch Thursday morning unless someone objects." That turns "I'll read it later" into "I'll read it now" or "I don't care enough to," and both beat a doc open in a tab for two weeks. Add a size estimate — "twenty-minute read; sections 3 and 4 matter" — because reviewers defer tasks of unknown length.
This is an ADR, and that is the point
Read the four back — an ask with a shape, options considered with rationale, decisions with their status, questions still open — and you have described an architecture decision record, or an RFC, or half a dozen formats engineers have argued about for years. That is the argument, not an admission. The docs get written that way; the request attached to them almost never is. "Can you look at this?" drops every field the reviewer needed and hands over 4,000 words with no index into it. The doc is an ADR; the ask is a shrug, and putting the structure into the ask is the cheap half nobody does.
When the design came out of an AI session
If you worked the design through with an assistant, you already generated the alternatives and argued three of them down — inside a session that is addressed to you and does not transfer. Pasting it in hands the reviewer your reasoning in the order you happened to have it, with nothing marking what survived.
RelayLink's briefing format carries the same four as first-class fields: options considered, decisions, open questions, and an ask with a response shape and an honest urgency. Your assistant assembles them from the private session; you review the exact package that will arrive, and confirming is what sends it.
One honest limit: none of this makes anybody read your design. It removes the excuses and makes a lazy reply visibly lazy — smaller than it sounds, still worth having. The reply is what you are designing for, and a reviewer holding your rejected options can produce a useful one in five minutes.
If a design doc is going out this week, connect your assistant and have it draft the ask that goes with it.