Dictating code review feedback that reads like a colleague, not a linter

There is a specific pull request you have been avoiding, and it is not the biggest one and not the riskiest one; it is the one that needs a careful, human response. The code questions are easy to type: introduce a variable here, add a test there, this block belongs in a helper. The hard part is the message underneath, about a design direction, a naming choice, or a concern that the branch is trying to do too much, and it is exactly where dictating code review feedback earns its keep, because a spoken concern is already half a draft. Typing a note like that feels like writing a formal document, so it waits, and while it waits, the branch merges with the concern still unspoken, or the teammate pings you and the conversation happens too late to shape the change.

The root cause is a mismatch between the medium and the message. Code review comments are typed, terse, and permanent, while the concern you actually have is conversational, tentative, and contextual. Dictating code review feedback lets the message start in the medium it was born in: speech. You can say the concern the way you would say it at a desk next to your teammate, with the hesitation, the hedge, and the reason included, and speech carries all of that without extra effort. In typing, the hedge costs you a paragraph of politeness, so you drop it and the note turns brittle. In speech, the hedge is a sigh that costs nothing.

The mechanics of the postponed review are also mechanical: you have two minutes of spare time, not the fifteen minutes a careful review seems to need. A typed review demands silence, focus, and a window in the calendar, while a voiced one can start as a commute thought, a walk between meetings, or a two-minute note on the way back from lunch. That start is the whole trick, because the review is mostly thinking, and the thinking can happen in a voice memo before the branch is even open. When you finally sit down at the machine, the memo is already the draft of the review, and you dictate the comments straight from it.

The practical habit is to keep a running voice note for the PR inbox: the branch name, the two hesitations you felt, the question you want to ask. Two minutes, no screen, and the note does the mental work of framing the review while you walk. Then when the review actually gets typed, the framing is done, and the typing is fifteen minutes rather than an hour. You will also notice that the branches you postpone are the fear-related ones, where you are not sure of your own judgment, and voicing the uncertainty makes it smaller. A review started in the hallway, in your own voice, is always easier than a review started as a blank comment box.

Before leaving any comment, argue with the code out loud, and argue in both directions. Present the author's case: the inline implementation keeps everything near the call site, which is actually a fair argument for a small method. Then present your case: the same logic appears in a second place, and two copies will drift. Hearing both arguments forces the real question, which is whether your concern is a defect, a taste, or a risk. Roughly eighty percent of review comments are taste, and taste comments are the ones that make peers dread the feature flag on their branch, so separating taste from defect before you type is the single highest-leverage move in review culture.

The out-loud argument has an additional benefit that reading alone does not produce: your sentence structure exposes the strength of your conviction. If you can state the problem in one clean sentence, it is a defect worth pressing; if it takes three hedged clauses, it is a taste you should soften or drop. Say the comment in its sharp form and then in its soft form, and choose the one that matches your actual certainty. This is the biggest reason dictating code review feedback improves review quality: the voice cannot hide uncertainty as smoothly as a well-crafted sentence of text can.

A surprising number of arguments dissolve completely once spoken, because the code is doing more than the diff shows. Say your worry: the filter is applied on the server, but the client is also filtering, and now we have two sources of truth. Then ask the agent to check the callers while you talk. The answer often is that the client filter was intentional and documented in a comment you skimmed, or that the server filter is new and the client one is dead. Reviewing with a question in hand, spoken aloud and then handed to an agent, converts your instinct into evidence in under a minute. Review by assertion is slow, while review by question is fast.

Keep a spoken log of the arguments you lose, because your own losing arguments are a record of your taste getting better. Six months ago you would have demanded a registry instead of the conditional that is now in the code, and the code is better than you expected. Say that honestly to yourself and to the author when appropriate: I was going to push back on this, but the inline version reads fine in context. A reviewer who concedes in public builds more credibility than one who is never wrong, and the team notices. Public concession also trains the author to come to you with a defense, which turns reviews into conversations rather than verdicts.

The difference between a checklist and a colleague is structure. A checklist says: rename this, move that, add a test. A colleague says: I want to make sure we are not going to regret this six months from now, and here is the specific reason this pattern worries me. When you dictate, aim for the second shape, and the easiest way is to dictate your comment as two sentences: what I noticed, and why it matters to me. The first sentence names the object, the second gives the motive, and the motive is the part that makes a comment feel like a person. A comment with a motive is answerable too, so the teammate can say: I considered that, and here is the trade I made.

Dictate at the level of the outcome, not the style: I keep wanting to know whether the retry is bounded, rather than this loop should have a max retry count. The first phrasing reads like a colleague curious about the design; the second reads like a linter with opinions. You can dictate the same content in either form, so the craft is in the phrasing, and it comes fast when you imagine the voice in your head is the teammate's, not the linter's. Practicing this phrasing on a low-stakes branch is the best training ground, because the phrasing is a habit that takes a dozen reps to internalize.

Then convert the dictated note into a review comment with structure, because even the warmest comment needs enough precision to act on. The shape that works: the observation, one sentence; the reason it worries me, one sentence; the question or the suggested direction, and it is fine if the direction is a question. Dictate all three in one breath and let the assistant keep the wording, then read the comment aloud before saving it. If it still sounds like a checklist, you have not found the motive, and spending one more spoken minute to locate the real concern is the cheapest way to improve the entire review culture you are a part of.

Avoid the imperative-only comment habit entirely; it is the fastest way to make a junior engineer defensively reword the code without understanding the reason. Say instead: can we check the gap between the two validation passes, because I am worried the second one never runs. That is a comment a colleague would leave, it is dictatable in one breath, and it produces better code than rename this to betterName ever will. Reviewers who write like a colleague also get read: the author opens the review looking for feedback they can use, and a person-shaped note is the kind they act on, while a checklist-shaped note is skimmed and half-ignored.

Written comments are already written, so before you send the review, decide if one of the notes deserves a call, and the rule is simple: anything where you would be uncomfortable if the author responded with an emoji and moved on deserves a synchronous walk. The awkward-feeling notes, the design-level concerns, the ones that will make the author defensive, these are call material. Book fifteen minutes and walk the notes in order of importance, not in diff order, and start by saying what the branch does well. If you cannot name one good thing in the branch, the branch has a bigger problem than the notes, and the call should start there.

On the call, walk the diff together with the comments open, and let your speech be the annotation. Point at the line, say the observation, say the worry, stop. Give the teammate room to answer before you offer a solution, because the answer often resolves the concern, and a comment that gets resolved in conversation never needs to become a blocker. The voice does the tonal work that text cannot: the same sentence that sounds stern in a comment box sounds curious in speech, and the teammate registers the tone instead of the formatting. Most notes that feel hostile are only hostile until they are spoken.

Agree the outcome per note out loud: consider it, please change it, or I was wrong and we drop it. Naming the outcome converts a discussion into a decision, and the author leaves the call knowing exactly what the review demands. Then dictate the taken decisions into the review as short comments, since the written record still matters for the merge queue and for the next reviewer. Use the call as anesthesia for the tough note, then leave the note in writing anyway, because the record is what survives and the walk is what made the record safe. A team that barely resembles a review culture starts to change right here.

Keep the calls as short as they can be, and do not fall into the review-call-as-code-review-meeting trap. Fifteen minutes, three notes max, and everything else stays in text. If the third note turns into a design debate, schedule the design discussion separately and close the call, because it is a different artifact with different stakes. The quick-call ritual also gives your reviews a deadline, since the call is booked at the same time as the review, and a review with a booked call gets written, while a review with an indefinite schedule waits for the ambient availability it never finds.

Habits survive on friction, and the voice review habit thrives because the friction is in someone else's hands: you think aloud on the walk, the notes exist before you sit down, and then the review is typing a memo you already gave. To keep it alive in a busy team, formalize the smallest version: one note per PR, dictated in under two minutes, the best note of your week. One dictated note a week is sustainable, spreads by example, and nobody on the team can call it overhead. When a teammate asks how you got so fast at reviews, tell them, and show them the two-minute ritual, because habit transfer in a team works by demonstration rather than by announcement.

The second preservation trick is pairing the voice review with the review of the review: occasionally open your own past dictated comments and read them aloud, asking whether the comment made the code better or just rearranged it. Teams that do this find their comments get shorter over time, and shorter comments are more read, which is the only metric that matters. Keep a shared, private voice note of review lessons: comments that worked, comments that backfired, phrasings that landed. The team voice notes become a living style guide, and they hold lessons that no lint rule will ever capture, because they are lessons about people, not about code.

The busy-team killer of this habit is the feeling that reviewing is already too slow, and the comeback is the branching habit: review drafts, not code. Dictate your review onto the message as soon as the branch opens, as a draft marked as such: draft review, one concern: the retry is unbounded, want to confirm it is on purpose. The author can ignore the draft until the review is real, but the draft fixes the thinking early, and it invites the author to answer the concern before the formal pass. A draft speech at branch-open time is a gift to the Friday version of you who has no time left and a review to write.

Finally, review in pairs once in a while: open a teammate's PR with them, dictate your thoughts as you read, and let them push back in the moment. In ten minutes, both of you have learned the team's review voice better than in a hundred written exchanges. The voice habit is not about the tool, it is about the medium: speech carries the motive, the hedge, and the concession that written notes strip away. A team whose reviews read like colleagues, because the reviewers thought like colleagues first, gets faster at reviewing and happier at it, which is the rarest combination in engineering culture, the moment two people argue with a branch out loud and both walk away respecting the argument, the review was done right.