A planning routine that keeps a refactor reviewable from the first commit

Dictating a Refactor Plan works best when you describe seams instead of intentions. A seam is a place where the code can be split without changing behavior: a function boundary, a module export, a repeated block that appears in three files. Walk the code you intend to change and name each seam with its file and its current responsibility. Then say which seam the refactor will move first. This list turns a vague goal such as clean up the billing module into a sequence of named places, and each named place becomes a sentence you can dictate, review, and check against a diff.
Write the reason for the refactor in one sentence that a reviewer can agree with. A reason such as the same total is calculated in four places and one of them rounds differently is useful; a reason such as the code is messy is not. The reason determines where the work should stop, because once the four calculations share one function, the stated problem is solved. Keep the reason at the top of the plan and refer to it when a tempting extra change appears. A refactor without a stop condition becomes an unplanned rewrite, and a rewrite is what reviewers rightly resist.
Map the call sites before you describe the change. List every place that calls the code you will move, every place that imports it, and every test that exercises it. Then mark which sites are inside the current module and which are outside. An internal move is cheap; an external move changes an agreement with other code. Speak the difference explicitly, and for each external site say whether the refactor will keep the current entry point or change it. When the map is complete, you know how large the blast radius is before a single line moves, and you can decide whether to reduce scope.
Choose the smallest first step that proves the plan. A good first step is one that touches one seam, keeps every external entry point in place, and can be reviewed in a few minutes. Speak that step in full before you speak the rest, because a plan whose first step is unclear is a plan that will be improvised from the first commit. Then stop and check whether the first step changes your understanding of the others. Plans improve when they are tested early, and a first step that is small enough to reverse is the cheapest test available, so take it.
An invariant is a statement that must remain true before and after every step. For a refactor, the most important invariants are usually behavioral: the same input produces the same output, the same errors appear in the same order, and the same public entry points remain callable. Write these as sentences and attach each one to a test that already exists or that you will add first. Then say that the refactor may not change an invariant without a separate decision. This single rule prevents the most common refactor failure, which is a behavior change hiding inside a reorganization. Write that rule at the top of the plan.
Name the public surface and treat it as frozen for the duration of the plan. List the exported functions, the configuration keys, and the error types that other code depends on. If a rename is necessary, plan it as a separate step with its own compatibility note. Speak the list before the first move, so every later request can refer to it. When the plan is reviewed, a reader can check whether a step touches the frozen surface, which is a yes or no question rather than a judgment about style. A frozen surface is what lets you improve the inside without renegotiating the outside.
Write a small set of quality invariants as well: the build stays green, the existing tests stay untouched except when a test names the old structure, and the diff for each step stays under a size you can read in one pass. A size limit sounds arbitrary, but it is a practical guard against a step that grows while you are inside it. Speak the limit as a number of files or lines that fits your review habit. When a step exceeds the limit, stop and split it rather than continuing. The limit is the signal that a refactor has quietly become a rewrite.
Add one invariant about naming. If the refactor renames concepts, write the old and new names in a table and keep the table in the plan. Then every request can use the new name and the review can check that no old name remains in a public place. This matters most when the plan is dictated, because speech drifts toward familiar terms. A naming table gives the spoken request a fixed target, and it gives the final search a definitive list. When the table is empty at the end, the rename is complete rather than merely mostly complete. Search twice before closing the step.
Order the steps so each one can be undone without undoing the others. Start with additive steps such as introducing a new function beside the old one, then move call sites one group at a time, then remove the old path only after the last caller has moved. This order keeps the code working at every checkpoint, which means a bad step can be reverted while the rest of the plan stays. Reversibility is not caution for its own sake; it is what makes a large refactor safe to review in small pieces and safe to stop halfway when a week goes badly.
Give every step a checkpoint with a named check. A checkpoint is a build, a test run, and a short manual confirmation that the behavior still matches the invariant list. Write the check next to the step before you start, so a step is never finished by feel. Then record the result of each checkpoint in the plan with a date. When a later step fails, the record tells you the last known good point, which is usually the difference between a five-minute revert and an afternoon of searching. A checkpoint that is not recorded is a checkpoint that did not happen.
Separate mechanical steps from judgment steps and do not mix them in one commit. A mechanical step moves code without changing it; a judgment step changes a name, a signature, or a boundary. Mechanical steps are easy to review and easy to trust, so they can be larger. Judgment steps deserve their own commit and their own explanation. Speak the classification for each step, because a plan that mixes the two forces a reviewer to verify everything at once. When the classes are separated, the reviewer can skim the mechanical work and focus on the decisions. That split repays the extra commit.
Plan the cleanup as the last step rather than the first. After the new path is in place and the old path is unused, there is a final pass for dead code, temporary comments, and compatibility shims. Write that pass as one step with a check that nothing calls the removed path. Do not let cleanup happen in the middle, because a half-removed path is harder to debug than either version. The last step is also where you update the plan and the readme, so the documentation matches the code that remains rather than the code you started with.
Speak the plan into the place where work is tracked, not into a scratch file that will be lost. A plan in an issue or a design note is visible to the reviewer before the first commit, which means objections arrive early and cost less. Say the reason, the invariant list, the seam map, and the numbered steps with their checkpoints. Then read the plan back as a whole and remove any step that does not serve the reason. A plan that fits on one screen is more likely to be followed than a plan that requires scrolling twice. Short plans tend to get followed.
Write each step in the imperative and name the files it touches. A step such as extract the rounding rule into one helper in billing totals, then update the three callers is reviewable; a step such as improve billing structure is not. Speak the file names exactly, because a spoken file name is also a check that you know where the change lives. If you cannot name the file, the step is not ready and should be a question rather than a task. The plan improves as the file names become precise, and precision is what makes a dictated plan useful to someone else.
Attach the acceptance check to each step in the same sentence. The check can be a test name, a build result, or a short manual confirmation. Then add one line at the end of the plan describing what will not be done, so a reviewer knows the boundary. When the plan is spoken, this line is easy to forget, and it is the line that prevents scope arguments later. Read the whole plan aloud once more and listen for steps that repeat or contradict. Repetition usually means two steps should merge; contradiction means the reason is not settled yet, and unsettled reasons produce unstable steps.
Use the spoken loop for the plan itself, not only for the code. Put the insertion point in the issue field or the notes file, hold the Voiskey shortcut, and speak one step at a time. Voiskey removes filler words and false starts and adapts punctuation to the field, so a step dictated as a thought arrives as a numbered instruction you can keep. Because it learns names and jargon, repeated module and function names stay consistent across the plan. A clean plan is the cheapest artifact in the whole refactor, and it is the one the reviewer reads first.
Review the diff against the plan, step by step, instead of reading the diff on its own. For each step, open the commit and check three things: the files match the plan, the check passed, and no unrelated change slipped in. Mark the step done in the plan with the commit reference. When a step does not match, stop and decide whether the plan or the code is wrong, then fix the one that is wrong in a separate commit. This comparison is the only reliable way to notice drift while it is still small enough to reverse. Record the reference the moment the step closes.
Watch for the two common drifts. The first is scope creep, where a step quietly improves something adjacent and makes the diff harder to review. The second is silent behavior change, where a move also alters an error message or an ordering. Both are easy to see when the invariant list and the step list sit beside the diff. Say the drift out loud when you find it, because naming it turns a vague discomfort into a specific correction. A reviewer who is told what to compare will find these faster than a reviewer who is asked whether the code looks good.
Decide in advance when to stop the refactor instead of pushing through. A failed checkpoint that cannot be explained in ten minutes, a frozen surface that must change sooner than planned, or a diff that grows past the size limit are all reasons to pause. Write the stop conditions in the plan and treat them as instructions rather than suggestions. Stopping at a clean checkpoint is not failure; continuing past a warning is how a reviewable refactor becomes an unreviewable one. Make each stop condition visible to the whole team, not only to you. The plan exists partly to make stopping an acceptable, documented decision.
When you want the same workflow on your own machine, download Voiskey for Mac and Windows and keep the shortcut ready while the plan and the diff are open. Voiskey turns a spoken review note into text at the insertion point, including file names and paths when you name them, which suits a step-by-step comparison. It removes filler and self-corrections and adapts formatting to the field, so a note about a slipped change arrives in a form you can paste into the review. Then close the loop by updating the plan and scheduling the next checkpoint. Then stop for the day.
Voiskey is a voice typing app for desktop use. You press a shortcut, speak one step at a time into the issue or notes field, and the text appears at the insertion point. It removes filler words and false starts, so the numbered steps can be reviewed before any code moves.
Voiskey learns names, jargon, acronyms, and spelling preferences. Repeating a module or function name in context helps it stay stable across a long plan. A naming table beside your notes gives you the same wording for each spoken step, and a quick read-back catches drift early.
Speak each step in the imperative, name the files it touches, and add the check that proves it worked. Voiskey clears self-corrections and adapts punctuation to the field, so the step reads as an instruction. Place the insertion point in the plan field before you start.
Yes. Voiskey types wherever the insertion point sits, including an issue field, a design note, or a prompt field, after you press the shortcut and speak. It also adapts formatting and phrasing, which keeps a numbered plan readable when it is pasted into a review.

Download Voiskey for Mac and Windows and dictate the next refactor plan.
Use it across macOS, Windows, iOS, and Android