A disciplined way to speak refactor and rename instructions, pass by pass

Voice Prompts for Refactoring succeed or fail before the first sentence is spoken, because scope decides everything that follows. A refactor with a vague scope becomes a rewrite, and a rewrite is risky, slow, and hard to review. Before you dictate anything, write one sentence that names the boundary: which files, which symbols, and which behaviors must remain identical. Then add one sentence that names what is out of scope. Read both aloud and check that a teammate would agree. If the two sentences conflict, the refactor is not ready to start. A scope you can say in two sentences is a scope you can defend.
Separate the mechanical part of a refactor from the behavioral part. Renaming a variable, extracting a function, and moving a block are mechanical: behavior should not change, and a failing check means the refactor broke something. Changing a default, adding a parameter, or altering an error path is behavioral: the output is expected to change. Most refactors mix both, so name which parts are mechanical and which are behavioral before you speak. The split determines how strict the verification must be, and it prevents the common mistake of judging a behavioral change with a purely structural check. The split decides how you check, and the check decides how safe the pass is.
Inventory the call sites before you rename anything. A name that appears in one file is a tidy change; a name that appears in forty files is a project. Use a search to count the references and note whether they cross module boundaries or public interfaces. If the name is exported, the change may affect code you do not own, so treat it as a public change rather than a private cleanup. The count is the honest measure of scope, and it belongs in the first sentence of the request. Speaking the number keeps the agent from treating a wide change as a small one.
Choose a refactor size you can review in one sitting. A change that touches one function and its tests is easy to judge; a change that touches the whole module is not. If the inventory is large, split the work into passes: rename first, extract second, reorganize third. Each pass gets its own prompt, its own check, and its own review. Splitting sounds slower and usually finishes faster, because a failed pass is cheap to revert. A refactor is only as safe as the smallest unit you are willing to review and undo. A reviewable unit is the only unit you can guarantee.
A rename prompt needs three things: the exact old name, the exact new name, and the scope where the change applies. Say them as separate sentences. Then add the naming rule the new name follows, such as a prefix, a suffix, or a casing convention. Without the rule, the agent may apply the pattern inconsistently across files. Without the scope, it may rename something you meant to leave alone. A precise rename request is short, but every sentence answers a question the agent would otherwise have to guess. Every short sentence closes one open question before it can cause trouble.
State whether the rename applies to identifiers, comments, labels, user-facing strings, or all of them. These are separate decisions, and each has different risk. Renaming an internal identifier is usually safe; renaming a user-facing label changes the product. Renaming a shared identifier changes the public surface. Say which of these categories the change covers, and if it covers several, list them explicitly. The most common rename failure is an agent that changes a label when you asked for an identifier, or the reverse. One extra sentence prevents that failure entirely. Naming the category is half of getting the rename right.
Describe the rule for exceptions before the agent finds them. A rename often has a few places where the old name must remain, such as a route, a stored key, or a compatibility alias. Say keep the old name in the route and the stored key, and change it everywhere else. Exceptions stated in advance keep the change consistent and stop the agent from improvising a policy. If you do not know the exceptions yet, run a search first and discover them before you speak the prompt. Guessed exceptions cost more than a two-minute search. A known exception is a rule; an unknown one is a surprise later.
Dictate one rename at a time, even when several names need to change. A batch of five renames in one prompt is hard to review and hard to revert, because a single wrong mapping can corrupt several files. Sequential renames let you check each mapping and keep the diff readable. If the renames are tightly coupled, such as a type and its matching handlers, do them in one pass but say the mapping explicitly for each pair. Speed here comes from clarity, not from compressing five decisions into one long sentence. Sequence is the only way to keep the mapping honest.
Order structural changes from the least disruptive to the most disruptive. Start with pure renames, then extract functions, then move code between files, then change interfaces. Each step has a different failure mode, and doing them in this order means a failure at a later step leaves the earlier work intact. Say the order aloud before you begin, and keep the list visible while the session runs. An explicit order also makes the review easier, because the diff can be read as a sequence of intentional steps rather than one large undifferentiated change. The order is the plan, and the plan is what makes review possible.
Keep every pass behavior-preserving until you decide otherwise. The safest refactor sequence ends each pass with the same observable behavior it started with, confirmed by the same check. When a pass must change behavior, mark it as a separate phase and stop calling it a refactor. This discipline matters because it keeps failures attributable; if behavior changed unexpectedly during a pass that was supposed to preserve it, you know exactly where to look. Blurring the line between cleanup and feature work is the most common way a careful refactor becomes a risky one. A pass that preserves behavior is a pass you can trust on its own.
Move code and rename it in separate passes. A move changes location, and a rename changes the name; combined, the diff becomes hard to follow and the version history loses the connection between the old and new files. Do the move first with the name unchanged, then rename in a second pass. The extra pass costs a minute and makes review straightforward. It also helps when you return later to understand why a file moved, because the two decisions are recorded separately instead of being tangled into one commit. Separate decisions make a cleaner story when someone reads the history.
Pause before any change that crosses a public boundary. A refactor that stays inside one module is a private cleanup. A refactor that changes an exported name, a route, or a shared type is a public change with downstream consequences. When a pass crosses that line, stop, name the boundary, and decide whether the change belongs in the same session. Often it does not. Splitting the public change into its own pass keeps the private cleanup safe and gives the boundary change the review attention it deserves. A boundary change deserves its own session and usually its own reviewer. That separation is what keeps the rest of the session calm.
Verify behavior after each pass instead of waiting for the end of the refactor. Run the same check you ran before the pass started, and compare the results. If the pass was mechanical, the check should pass unchanged; if it fails, stop and fix the pass before continuing. Record the result next to the pass number. If you use Voiskey, speak the result into the session note at the insertion point, so the verification trail builds itself while you work. Verification after each pass is what turns a risky refactor into a sequence of safe ones. The pass record is what makes the next failure easy to locate.
Keep the check small and stable across passes. A check that grows with each pass becomes hard to compare, and comparison is the whole point. Pick one check that covers the behavior you are preserving, and run it unchanged until the refactor ends. Add a second check only when a pass introduces a new risk that the first cannot see. Stability matters more than coverage here, because a stable check tells you whether a specific pass changed something it should not have. Stability turns a comparison into a real signal you can trust, rather than background noise you learn to ignore.
Record failures with the pass number and the exact input that exposed them. A failure report that says the refactor broke the form is hard to act on; a report that says pass three changed the empty-state label for long names is easy to fix. When you download the latest Voiskey build, rerun the recorded failure against the new version so a tool change does not mask a regression. Detailed failure notes are also the raw material for the refactor pattern library, because they show which passes tend to cause which problems. A specific note is the shortest path from a failure to a fix.
Finish with an end-to-end check that exercises the refactored code as a user would. Pass-level checks prove that individual steps preserved behavior; the end-to-end check proves that the assembled result still works. Run the main path, then the empty path, then one error path, and compare the outcome with what you recorded at the start. If everything matches, the refactor is complete. If something differs, the difference tells you which pass to revisit, and the pass-level record tells you where to look first. The record and the check together make the final review quick.
Document the refactor while the reasoning is still fresh. Write the goal, the scope, the order of passes, and the check results in a short note. Add the exact prompts or spoken sentences that produced each pass. The note is more useful than the diff alone, because the diff shows what changed while the note explains why. When a similar cleanup appears next quarter, the note becomes a checklist. Documentation written at the end of a session takes minutes; documentation reconstructed a month later often misses the decisions that mattered most. A short note written now beats a perfect report that never gets written.
Turn repeated refactors into named patterns the team can speak. A rename with compatibility aliases, an extract-and-test, and a move-without-modify are patterns with known pass orders and known checks. Name them, write one example for each, and use the name at the start of a prompt so everyone knows which sequence is coming. Named patterns reduce the variance between engineers and make review faster, because the reviewer knows what a careful version of that pattern looks like. A pattern library is the practical memory of a refactoring practice. A named pattern is a decision the whole team can reuse.
Review the patterns when the codebase changes shape. A pattern that worked in a single module may fail across a service boundary, and a rename pattern that ignored public interfaces may be unsafe once the interface is exported. Schedule a short review after a major structural change and update the patterns that no longer fit. Retire the ones that have become misleading. A pattern library that is never reviewed slowly turns into folklore, and folklore is harder to correct than no documentation at all. A review after every structural change keeps the library honest, current, and useful to the team.
Close the loop by teaching the pattern to someone who has not used it. Walk them through one pass, let them speak the next, and watch where they hesitate. The hesitation points are the parts of the pattern that need a clearer example. Update the note, not just the person. A refactoring practice spreads through shared, specific patterns, and it survives because the patterns are written down in the same place the team already looks for guidance. That is how a single careful refactor becomes a durable habit. Teaching is the test that shows whether the note is complete enough.
Voiskey is a system-level voice typing app. Press a shortcut, speak the exact old name, the exact new name, and the scope, and the text appears at the insertion point in your code editor. It removes filler words, stutters, false starts, self-corrections, and grammar slips, so the names in the prompt stay clean and the request stays easy to review.
State the exact old name, the exact new name, and where the change applies. Add the naming rule, such as a prefix or casing convention, and say whether identifiers, comments, labels, or user-facing strings are included. Name any exceptions in advance, such as a route or compatibility alias that must keep the old name. These details keep the rename consistent across files.
Yes. After each pass, speak the result into the session note, and Voiskey places it at the insertion point. It removes filler words, stutters, false starts, and self-corrections, so the record stays short and readable. Keeping a result next to each pass number makes a failing pass easy to find, and it preserves the verification trail when you resume the refactor later.
The text appears at the insertion point in whatever app or text field is focused, including your code editor. Voiskey turns spoken requests into AI-ready prompts, including file names, paths, and commands, and it learns names, jargon, acronyms, and spelling preferences. It supports 100+ languages and translation, so a rename rule full of project terms can be spoken in the language you prefer.

Download Voiskey for Mac and Windows and dictate clean refactor and rename passes.
Use it across macOS, Windows, iOS, and Android