Software & TechnicalFree
Technical Design Document Review Checklist
River reads another team's design document against what your services actually do, then writes the comments only you could have written.
Page one for this query is checklists, and it is largely the same checklist. Is the problem clearly stated. Were alternatives considered. Is there a rollback plan. Is monitoring covered. Those are fair questions, and a competent author has answered them already, which is why a review built on them returns comments the author could have written alone. Halstock's slot reservation design drew 31 of those across two reviewers. Twenty-two were exactly that kind.
Halstock is an illustrative online grocery. The document made 23 statements about the inventory service, which a different team owns. Six were checkable in the published reference. The other 17 were assumptions the author had no way to test, and settling them is the whole of what a reviewer adds. Eleven held. Four were wrong, three of those in ways that change the design, and the dependencies section listed nothing at all for the inventory team.
Built for the engineer handed an hour and somebody else's document. Reading 4,100 words takes 19 minutes of that hour, so the question is where the other 41 go. Run it on a design you have been asked to approve, or on one you were only copied into. Writing the document in the first place is an RFC and design doc pack, and the interface it proposes is an API design review. What your own estate actually does, as opposed to what the diagram claims, is an architecture reconstruction.
Three things only the reviewer can settle
An author writes what they believe about a service they do not own, in good faith, and the belief does not look like one on the page. Separating those statements out and marking each confirmed, contradicted or unverifiable is the one job nobody else in the review can do. The keyword carries weight as well. There may exist valid reasons in particular circumstances to ignore a particular item is what should means, and five of Halstock's fourteen described inventory work.
The sharpest of the four reads fine until you happen to own the service. The specification is precise: a request method is considered idempotent if the intended effect on the server of multiple identical requests is the same as the effect for a single such request. The reserve endpoint is, keyed on the request id, for 60 seconds, and the design retries at 300. Widening that window is not a configuration change either. The deduplication store goes from 74,400 live keys to 744,000.
Then the arithmetic the author had no numbers for. The inventory service peaks at 1,240 requests a second against a ceiling of 2,000, so 760 of headroom, and the design projects 900 more at that same peak. Versioning the payload means 14 consumers validating strictly, nine of them outside the team. Six days for the first, four for the second and nine for the third, against a dependencies section that asked the inventory team for nothing at all.
How it works
Bring the document
The design doc, RFC or one-pager, however finished. Diagrams help but are not needed here.
Say what you own
The services it touches on your side, their contracts, their limits and their measured load.
Read the claims
Every statement it makes about you, marked confirmed, contradicted or nobody can say yet.
Post the comments
Each one names the thing on your side that breaks and what it costs to accommodate.
What you get
- Every claim the document makes about your systems pulled out and marked one at a time
- Assumptions split into confirmed, contradicted, and the ones nobody can settle yet
- Each contradiction carried through to what specifically breaks in the proposed design
- The load it adds set against your measured peak and the ceiling you actually run under
- Work landing on you costed in engineer-days, whatever the dependencies section claimed
- Normative keywords counted, so a requirement on you written as should gets flagged
- Comments written ready to post, each naming an artefact on your side and a consequence
- Questions you cannot answer yourself listed as questions rather than guessed at
Common questions
We already have a design review checklist.
Keep it, because somebody has to ask whether there is a rollback plan. This is the other half, and it is the half only you can do. Twenty-two of Halstock's 31 comments were checklist comments, three touched the inventory service at all, and exactly one of those three said what would happen as a result.
The author is on my team. Is this overkill?
Less useful, and not useless. The mechanism keys on ownership rather than on team boundaries, so it fires wherever the document asserts something about a component the author does not run. Inside one team that is usually two or three statements instead of 17, and they are still the ones worth checking first.
How do you know an assumption is wrong?
By checking it against what you gave me rather than against a general sense of good practice. Halstock's idempotency claim was true and still wrong, because the window is 60 seconds and the retry is at 300. That distinction only exists if somebody reads the actual behaviour of the actual service.
Is this not just being difficult in review?
The opposite, and the format is the difference. A comment saying to consider caching invites an argument. A comment saying the design adds 900 requests a second onto 760 of headroom invites arithmetic, and arithmetic converges. Every comment names an artefact, a consequence and, where there is one, the fix.
The document is a five-slide deck, not a doc.
Then there are fewer claims and more silence, and the silence becomes the output. The unstated assumptions get listed as questions with the answer you would need, which is a more useful review of a thin document than marking it thin. It says which three answers would let you approve it.
What about security and privacy?
Treated the same way, as claims about your side to confirm or contradict, so an assumption that a field is already encrypted at rest gets checked rather than accepted. Working out the attack surface a new design creates is a different exercise and belongs in a threat model.
What do we actually get back?
A sheet holding one row per claim with its verdict, evidence and the comment to post, plus a document grouping the findings by whether they change the design, the timeline or nothing. Halstock's came to 12 comments and 19 engineer-days of work the solution architecture document had not accounted for.
Technical Design Document Review Checklist
Fill in the form and your workspace opens with the work already underway.