dictate commit messages prs: A Practical Guide to Dictating Commit Messages and PR Descriptions

Commit messages and PR descriptions carry the why, and you can dictate commit messages PRs and their descriptions at the same moment the work finishes. The message is not a log entry; it is the reasoning that code review needs and that the blame view conveniently strips away. Most messages fail because they are typed after the energy is gone, when the trade-offs have already turned into trivia. Dictating right after the green test keeps the decision fresh. Speak the story once, roughly, and let the tool clean up the restarts; what lands is usually longer and more honest than what you would have typed.

The typing gap is the whole argument for this habit. You speak at around 220 words per minute and type at around 45, so a change that took you two hours to build can take five minutes to describe in prose. The version you would say out loud usually contains the context that the typed version leaves out: the alternative you rejected, the workaround you avoided, the thing you would have done differently on a second pass. None of that appears in a diff. It only exists in your head, and your head clears fast. Immortalize the explanation while it is still cheap.

The audience for the message is not you tomorrow; it is the person reviewing the PR and the person debugging in six months. Write for the person who sees only the diff and wonders why. If you cannot explain the change in three sentences, either the change is too big to review or you have not understood it yet, and speaking the explanation out loud surfaces that immediately. Dictate first, then split the commit if the story itself is too long. A message that tells the whole story also makes the review smaller. The message is the cheapest place in the pipeline to spend thirty seconds.

Trigger the habit at the moment the tests go green, before you push. Open the commit box and say the change in three beats: what changed, why it changed, and what you ruled out. Thirty seconds of talking is usually enough, and it beats the five minutes of staring at a blank message that most developers can recognize. Do not write the message down first; saying it first forces you to describe the work in order rather than in fragments. The fixup commits and the rebase details come after, once the story exists. The order matters more than the wording ever will.

Example: you moved the retry loop out of the request handler because timeouts were blocking the queue, and you dropped the exponential backoff for now. Say exactly that, roughly, and the dictation turns it into three lines: the behavior, the motivation, the boundary. Names come out formatted the way you type them, so service names and flag names land correctly rather than being spelled out. Then edit the result the same way you would redraft anything: cut the obvious, keep the reasoning, and add the ticket number at the end if your tracker needs one. The best messages sound like a person who just finished the work, not like a changelog generator.

Conventional commit style works with dictation too. Say fix(api): retry on 429 without blocking the queue, and the type and scope come out as part of the spoken line; you only need to check the casing. If you speak the whole subject line as one phrase, the pattern stays consistent without building a rules engine in your head. Keep a one-line template pinned beside the commit box: type, scope, subject, body, ticket. When the template is constant, the body is the only thing that needs thinking, and that is exactly what voice is good at. The template is a scaffold, and the story is the load it carries.

A PR description is a pitch to the people who will read your code. Dictate it in the template order so nothing gets skipped: problem, approach, tests, risk. The problem section is one spoken sentence, usually the message from the commit. The approach is where the story belongs: say how you solved it and why this solution and not the obvious alternative. Do these two sections out loud while the branch is still open, before you start writing the code, so the description acts as a checklist rather than a recap. Filling the template by voice is faster than filling it by hand, and the spoken version is the one with the actual reasoning inside it. Reviewers read the approach section once, so make that pass count. Ask the PR to state the change the way you would in a review, and the rest of the description writes itself.

The approach paragraph is where reviewers spend their attention, and it is where dictated writing beats typed writing. Talk through the trade-off the way you would explain it in a code review, with the concrete reason you chose one strategy over another. Say what the reader expects to see and what is deliberately missing, such as the pending migration or the follow-up cleanup. Reviewers ask fewer questions when the description already answers them. A doc that sounds like a person reasoning beats one that sounds like a template, and speaking is the fastest way to sound like yourself. Editing is where the message earns its keep, not where it gets embarrassed. Say the thing you would argue about at the whiteboard. Then let the description say it for you.

Finish with the tests section because it is the least debated and the most skipped. Narrate what you ran, what you skipped, and how someone else can verify the change in one minute. Say the command that reproduces your run, the environment it ran in, and the one case you could not cover. If you skipped a test because the setup is painful, say that too, because a reviewer will ask about it anyway. A spoken test summary that takes forty seconds saves a reviewer a fifteen-minute local checkout. Check the body if the subject line is ambiguous, and say the reason in the body even when the subject says it all. The tests section is the one a reviewer can verify without you, so the command you ran has to be stated exactly.

The most expensive part of review is not the review itself; it is the round trip. The first comment on a PR is usually a question that the description could have answered: what did you already try, why is this flag here, what breaks if this is removed. Dictate those facts into the description up front. Reviewers notice context that is volunteered, and they stop asking questions you already answered. List the related work, the follow-up tickets, and the things you deliberately left for another change. The description is the handshake, and the handshake is what prevents the round trip.

When a reviewer does leave comments, answer them one by one with your voice. Click into the thread, dictate the explanation, and move on; the effort of a thorough answer drops from a paragraph to a sentence. Match the comment to the change: if the review asks why a function exists, the answer is usually the trade-off you already dictated in the message, and you can point at it directly. Keep replies short, factual, and addressed to the argument rather than to the reviewer. Context accumulates with each answer and the PR closes faster. Roughly stated answers are still answers, and the review survives on them.

Update the description as the review moves, because a PR that changes in response to comments is a PR where the context shifts. Dictate the resolution of each thread into a line under a review notes heading, so the next reviewer sees your reasoning without reopening threads. If a comment suggests a better approach, say what you changed rather than just agreeing. The description then reads like a history, which is exactly what anyone returning to the branch after a week needs. Stale descriptions cause duplicate questions; current ones end them. Threads, once resolved, are history, and history belongs in the description.

Habits need a trigger, and the cleanest one here is the moment before you push: tests green, branch tidy, cursor in the commit box. Do the dictation at that instant, every time, even when the change is tiny, because the small commits are where the habit forms. Sixty seconds of speaking is the whole routine. If you miss the moment, the fallback is the minute after the standup, when the work is still the story of the day. A commit message dictated late beats one never written, but only just. Sixty seconds is short enough to defend against a busy day, which is exactly why the trigger works.

The vocabulary part gets easier by default. Voiskey learns repo names, service names, function names, and internal codenames, so a message about the auth middleware does not require spelling out every token. Teach it once and the same terms come out the same way on your work laptop, your personal machine, and your phone, so the dictation stays reliable wherever the commit happens. Consistency matters at scale: a team with shared vocabulary produces messages that every subsequent reader can parse without decoding the author's private shorthand. Shared spelling is a kind of code style: it makes the message readable without a translation pass.

Measure the habit, not the prose. Count the commits that need a follow-up explanation in the thread, the review questions that the description already answered, and the number of times you rewrite a subject line twice. Those three numbers tell you whether the routine is improving the review, independent of how polished each message looks. Review your own last five messages at the end of the week and dictate a better version of any weak one. The habit compounds because every fixed message teaches the next one. A week of honest messages is the only benchmark worth keeping, and templates are just the shape.