Ilango RajagopalArticlesSeriesProjectsNow
Planning

Reviewing a design doc: comments that change the decision

October 14, 2026

The win for today: a written review of a design doc you did not write — the Tsundoku search doc — with each comment tagged by kind and severity and tied to a section, and a verdict with the one thing that would change it. About forty minutes. Do not open the exercise doc until section 4.

What to do (read this first)

  1. Read the reviewer's form — three passes, one comment shape, a verdict. Five minutes.
  2. Do the sorting drill in section 2 so you know a useful comment from a remark before you write any.
  3. Open the exercise doc, read its header, and review only what it asks for. Twenty minutes, three passes, comments in the shape.
  4. Write the verdict. Run the checklist. Send me the review.
Key idea —

You already know everything a reviewer needs to check — it is the author-side rules from lessons 1–5, turned around. The skill in this lesson is restraint: comment on the decisions the header asked about, tie every comment to a goal or a section, end every comment with a question or a change, and leave taste at the door.

1. What you are checking, and why (4 min)

Ubl's Design Docs at Google gives the reviewer's job in one line: bring experience to bear while change is still cheap. Not to approve the prose, not to show what you would have built — to find the thing the author could not see.

Sourcegraph's status labels tell you what to read for: under "Reviewing problem" you check that the problem definition is correct and ignore the design; under "Reviewing solution" the goals are agreed and the design is open. Slatton's rule that a doc should never surprise the reader is your detector — every place you stop and think "wait, what about…" is a comment, and every place you think "I'd have done it differently" is probably not.

Each author-side rule becomes a reviewer's question. Goals: outcome or design choice? checkable? Non-goals: would anyone have expected it? Context: any opinion in it? Design: choice, reason, cost, acceptance — all four? Alternatives: real, and dismissed with a reason? Open questions: any decisions hiding in there? Claims: a number behind every adjective? Cross-cutting: present, and about the obvious concern? That list is the three passes in the reference.

2. Comment or remark? (5 min)

Comments on a hypothetical search design. Sort each.

Would this comment change the decision?0 of 8

"I’d have used Bleve."

"Goal 1 says 200 ms on 50k items; §3 never says how the index is loaded at start-up. Cold start could blow that — how is it loaded?"

"This is great, nice work."

"§4 dismisses FTS5 as ‘too limited’ without saying what it lacks for goals 1–5. What does it lack?"

"A few typos in §1."

"§3: the index ‘updates itself’. What process triggers reindexing, and what about items fetched in the background?"

"Have you considered Elasticsearch?"

"§5 is missing. Saved page text is user data on disk — what is the disk-growth and deletion story?"

3. The comment shape (3 min)

A remark
Not sure Bleve is the right call here, FTS5 might be simpler.
A review comment
[challenge][should] §3, §4 — Bleve is chosen for being pure Go and having highlighting, but FTS5 is dismissed in §4 without a reason, and SQLite is already the store. Which of goals 1–5 does FTS5 fail? If none, the simpler choice needs a reason to lose.
Kind and severity pre-sort it for the author; the section anchors it; the question is one they can answer in the doc. The remark gets a shrug; the comment gets a paragraph in §4.

4. Do it (25 min)

Open the Tsundoku search design doc. It is a fictional project; the author is not you. Read the header first and review what it asks for. Three passes, comments in the shape, five to ten comments, verdict last. Write it in a Markdown file as if you were going to paste it into the Discussion.

The doc has flaws of the kinds you have learned to avoid, and some things it gets right. The answer key is in NOTES.md in this workspace, under "Tsundoku key" — do not read it until you have sent me the review.

Self-review: the review0 of 7

5. Retrieval (2 min)

One of these is from lesson 7.

Q1. A review comment is useful when it:

Q2. As a reviewer, you review:

Q3. A verdict of 'request changes' must name:

Q4. Public review replies mostly turn out to be:

Nothing new. Re-read the Rust RFC template as a reviewer: its Drawbacks, Rationale and alternatives and Unresolved questions prompts are the three questions a reviewer asks of any design section.