Reviewing AI-Written Code with a Spoken Checklist

A read-aloud checklist that turns generated code into findings you can act on

Voiskey Voiskey Team
Voice Vibe CodingAI Code PromptsReviewing Ai-Written Code

Build the Checklist Before You Read

Reviewing AI-Written Code with a spoken checklist starts by writing the checklist before you open the diff. A generated change looks plausible at a glance, and plausibility is exactly what makes a loose review feel sufficient. Write six to eight questions you will ask of every file, phrased so the answer is short: does this file have one job, is every name one we agreed, is there code we no longer call, does each branch have a visible outcome. Keep the list on one screen and read it in the same order every time. The order matters, because a review that jumps between concerns tends to stop as soon as the code stops looking strange.

Phrase the questions for the ear rather than for a form. A question you can answer in one sentence while reading aloud is more useful than a category heading such as quality. Does this function return the same shape for every branch is answerable; is this function good is not. Rewrite any question that invites a speech rather than a finding. Then decide what a bad answer looks like, so the review has a definition of done. A checklist where every question can be answered fine without evidence is a ritual, and rituals are what generated code needs least. Write the answer you expect before you read the code, so the review has something to contradict.

Set a time box and a stopping rule before the first file. Thirty to forty minutes is enough for a small change, and the stopping rule is the end of the checklist rather than the end of your patience. When the box closes, record the remaining unanswered questions as findings with a scope note, and either extend the review deliberately or ask for a smaller change. Do not let a vague worry keep the review open indefinitely, because an open review blocks every other decision. A closed review with three known gaps is more useful than an open one with no record.

Decide where findings will be written before you start reading. The best place is next to the code, in a comment or a note attached to the changed block, because a finding separated from its line loses meaning by the next day. Use one format for every finding: file, line or block, what you expected, what you found, and the smallest fix you would accept. Speak that format once to hear how long it takes, then keep it terse in practice. The format is what makes a spoken review comparable with a written one, and it is what lets someone else act without a meeting.

Walk the Diff Aloud, File by File

Read the diff from the entry point outward, not from the top of the list downward. Find where the user action enters, follow it to the first changed function, then continue into the helpers it calls. This order matches how the code will run, so a missing link appears as a break in the story rather than as a detail you might scroll past. Say the path out loud as you go: the button calls this handler, the handler calls this validator, the validator returns this shape. When you cannot say the next step, you have found the most valuable kind of finding.

Read each changed block in full, including the lines around it that did not change. Generated code often fits the new lines well and duplicates a helper that already exists three blocks above. Say what the block does in one sentence, then compare that sentence with the function name. A mismatch is a finding even when the behavior is correct, because the next reader will trust the name. Also say which inputs can reach the block; if you cannot name them, the branch may be unreachable, and unreachable code is a maintenance cost that never shows up in a demo.

Keep the pace steady and resist editing while you read. The moment you start fixing, the review stops being a review and becomes a debugging session with no record of what you noticed. Write the finding, finish the file, then fix. This separation matters most for generated code, where a small fix often reveals a second issue two lines away and pulls you into a chain with no boundary. When a finding is large enough that finishing the file feels pointless, stop the walk, write the finding, and request a smaller change instead. Marking it takes one line and keeps the rest of the file reviewable.

At the end of each file, answer the checklist questions in order and write one line per answer. Yes or no is enough for most of them; a no becomes a finding with a location. Say the summary sentence aloud before moving on: this file does one job, uses agreed names, and leaves one unreachable branch. The sentence is a compression of the review and a test of whether you actually understood the file. If the sentence is hard to form, return to the block that caused the difficulty rather than moving to the next file with a vague sense of unease.

Question Every Dependency and Branch

Question every new dependency as if it were a line of code you must maintain. Ask what the new package replaces, whether the same result is possible with what the project already has, and what happens if the package is unavailable. A generated change can introduce a library for a single helper, and that addition outlives the feature that justified it. Write the answer next to the import so the next reviewer does not repeat the question. If the answer is that the package saves twenty lines, say so plainly; the goal is a recorded decision, not a ban on dependencies.

Walk each branch, including the ones that look obvious. For every conditional, name the condition, the path taken when it is true, and the path taken when it is false. Generated code often handles the true path in detail and leaves the false path to a default that was never designed. Say what the user sees on each path, then check whether a test covers both. A branch without a visible outcome is a candidate for deletion, and a branch without a test is a candidate for a finding. Two sentences per branch keep this step fast enough to do for real.

Check the boundaries between files rather than only inside them. When a change crosses a component boundary, name the shape passed across: which fields, which optional values, which errors. Most integration failures in generated code come from a shape agreed in one file and assumed in another. Say the shape once, then look for the second definition and compare. If the two disagree, the finding is specific and cheap to fix. If you cannot find the second definition, that absence is itself the finding, because it means the contract lives only in the caller's expectations. A contract that exists only in a caller is a contract nobody can verify.

Close the section by rating each finding rather than each file. A finding that breaks the named behavior is blocking; one that hides a failure is serious; one that only affects naming or structure is a cleanup. Write the rating next to the finding and sort by it. Ratings stop the review from ending in a flat list where a typo and a silent default carry the same weight. They also make the conversation with the author short, because the blocking item is already marked and does not need to be argued back into view. A sorted list also makes the final summary a matter of reading down, not recalling.

Turn Findings into Small, Verifiable Fixes

Turn each finding into the smallest fix that makes the finding false, and describe that fix in one sentence before prompting. A finding such as the empty branch returns undefined becomes add an explicit empty result and a test for it. The sentence is the prompt, and its smallness is the safety property: a fix that touches one behavior is easy to verify, while a fix that rewrites a file restarts the review. Use Voiskey to dictate these fix sentences directly next to the finding, so the description and the code stay in the same place. Then send the prompt and check the exact behavior the finding named.

Fix in order of rating, and stop when the blocking items are closed. Serious findings can be scheduled with an owner and a date; cleanup items can be batched at the end or left for a follow-up change. This ordering is what keeps a review from expanding into a rewrite, which is the most common way a small generated change consumes a day. When a blocking fix reveals a second blocking issue, record it and continue with the current one rather than opening a third front. The count of open blocking items is the only number that needs to stay at zero before you move on.

Verify each fix with the check that produced the finding, not with a fresh demonstration. If the finding was a branch that returned nothing, run the branch and look at the result. If the finding was a duplicated helper, confirm the duplicate is gone and the remaining call sites still work. Then run the tests you already have, because a small fix can break a neighboring case that the finding never mentioned. Keep the verification note next to the finding, with the date and the command you ran. Verification notes are what turn a review into evidence rather than opinion.

Bundle the work so another person can reproduce it. A teammate should be able to download the branch, run the same commands, and see the same findings close. Note the order in which the fixes were applied, since later fixes sometimes depend on earlier ones. If a fix was rejected or deferred, say why in the same record instead of leaving a silent gap that looks like an oversight. Clear the record when the change merges, and carry any deferred items into the next task with their owner attached. The bundle is done when someone else can retrace the review without asking you a question.

Keep the Checklist Alive Across Changes

Review the checklist itself after every few reviews and delete questions that never produce findings. A list that grows without pruning becomes a reading exercise, and a reading exercise gets skipped under time pressure. Keep the questions that caught something real, reword the ones that produced vague answers, and add one question when a new failure mode appears. Store the list with the project so it is versioned with the code it reviews. A checklist with six live questions beats one with twenty inherited ones, and the difference is visible in how long a review takes. A list that never changes is either perfect or unread, and it is rarely perfect.

Add project-specific questions as the codebase teaches you its traps. If a past change broke because a date was formatted in two places, add a question about where dates are formatted. If a generated helper once duplicated an existing one, add a question about searching before adding. These questions are the memory of the project, and they are worth more than any general advice because they encode a specific scar. Write each one as a question with a short example, then test it on the next change to see whether it earns its place. A question with no example is the one most likely to be answered generously.

Share the list with anyone who reviews the same code, and compare answers on one change. Two reviewers using the same questions produce comparable notes, which makes disagreement about a change specific instead of stylistic. Where they disagree, the question is usually ambiguous; fix the question rather than the reviewers. Review the shared list once a month and keep the changes small, so nobody has to relearn the whole thing. A shared checklist is one of the cheapest forms of consistency available to a small team. Disagreement about a question is cheaper to resolve than disagreement about a change, and it leaves a better record for the next reviewer who joins the team.

Retire the list when the code around it changes shape, and start a new one from the questions that still bite. A checklist written for a single-page prototype reads strangely over a routed application, and forcing it invites answers that mean nothing. Keep the old list in the project history for reference, then write the new one in the same format and run it on the next change. The habit worth preserving is the ritual of asking in a fixed order, not the specific questions, because the questions are always a snapshot of what the code was like when you learned to fear it.

FAQ s

Voiskey is an AI voice typing app that works at the system level. Press a shortcut, speak, and text appears at the insertion point in any app or text field, so a review note can be dictated next to the block it describes. It removes filler words, stutters, false starts, and self-corrections, which keeps a spoken finding short enough to act on. That means the checklist answer and the fix sentence live beside the code rather than in a separate scratch file.

Voiskey learns names, jargon, acronyms, and spelling preferences, so repeated function and component names become easier to dictate as a review proceeds. It supports more than one hundred languages and translation as well. Say a new name slowly once and correct the spelling where it appears, and later notes are more likely to match the code. For exact identifiers in a fix prompt, type the fragment and keep the explanation spoken.

Use one spoken format every time: file, block, expected, found, smallest fix. Voiskey clears filler and shapes punctuation to suit the task, so the note arrives terse enough to read later. Dictate the note where the finding belongs instead of collecting findings in a separate list, since a note separated from its line loses meaning quickly. Then rate each note as blocking, serious, or cleanup so the next action is obvious.

Yes. Voiskey works at the system level in any app or text field, so the same shortcut and speaking habit apply whether you are annotating code or writing a review summary. You speak, the text is polished and typed at the insertion point, and you edit in place. That consistency matters during a review, because switching tools to write a note is often the moment the finding stops being recorded.

Say less. Get more
Say less. Get more
Say less. Get more
Say less. Get more
VoiskeyVoiskey

Your voice, amplified.

Download Voiskey for Mac and Windows and dictate review findings beside the code.

Use it across macOS, Windows, iOS, and Android

Use it across