A design brief and test method for commands a device agent can follow

Designing Clear Voice Commands begins with a brief, not a phrase. Write one paragraph describing the task, the person who performs it, the screen in front of them, and the result they need. Name the object that will change and the moment the change should happen. This brief forces you to separate the work from the wording, which is where most confusion starts. A phrase written before the brief tends to describe what the author remembers rather than what the operator needs. Keep the brief to half a page and read it aloud to the operator before you draft a single command. Their corrections at this stage are cheap and specific.
Add the constraints that shape the wording. How long does the operator have to speak? Are their hands free? Is the room quiet enough for a normal volume? Which words are already used for something else in this workplace? Constraints are not obstacles to design; they are the material you design with. A command that ignores them will be rewritten in the first week. Write each constraint as a short sentence and mark whether it is fixed or negotiable. Negotiable constraints are where you have room to trade a little speed for a lot of clarity. Ask the operator to name the constraint they notice first, because that is the one a command usually breaks.
Define the failure budget for the command. Some tasks can tolerate a retry, and some cannot. A note added twice is annoying; a file moved to the wrong folder is worse. Write what a failure looks like, who notices it, and what recovery requires. This budget decides how much confirmation the command needs and how precise the object must be. A command with a generous failure budget can start simple. A command with a tight budget needs a named check before the action runs, even if the check slows the sentence by two seconds. Write the check as a sentence the operator can say, not as a principle they must remember.
Approve the brief with the operator and one other person who understands the task. Ask both to describe the command they expect in their own words before you show any draft. If their descriptions differ, the brief is still incomplete. Record the differences and resolve them in writing rather than in conversation. Date the approved brief and keep it beside the command library. The brief is the reference you will use when a later disagreement arises about what the command was supposed to do, and it saves everyone from arguing about memory. Reopen the brief whenever a command changes, so the reference never falls behind the library.
Put the action first, the object second, and any value last. This order matches how a listener builds a plan: what to do, to what, with which detail. It also matches how a polished instruction reads after filler words disappear. When the order changes, the agent has to hold the sentence open longer, and the operator has to remember where the value went. Pick the order once and use it for every command in the library. Predictability is the design goal, not variety. An operator who knows the order can speak while looking at the screen instead of at a card.
Keep the subject out of the sentence unless the subject is the object. Most device commands do not need I want you to or could you please. Those openings add length, they invite the agent to interpret a request as a conversation, and they disappear under time pressure anyway. Start with the verb and trust the context. If a workplace culture needs a softer register, add one short word at the end rather than a full clause at the start. The softer word survives polishing; the preamble usually does not, and losing it mid-sentence confuses the operator. The register belongs in the brief, not in every command.
Choose concrete nouns over categories. Say the exact folder name rather than the project folder, the exact file name rather than the report, the exact setting rather than the display option. Categories require the agent to resolve a reference, and resolution is where ambiguity enters. If a category name is genuinely useful, define it once in the brief and write the members beside it. Then either say the member or accept that the command needs a confirmation step. Concrete nouns also make the command easier to verify, because the operator knows exactly what should appear on screen. Write the exact name on the card, and update the card when the name changes.
Give each command a single destination. A sentence that both writes text and changes a device state asks the operator to check two results at once. Split it into two commands with a pause between. The split feels slower in planning and faster in practice, because each result can be confirmed before the next sentence begins. Write the destination on the card next to the command so nobody has to remember whether it produces text or action. One destination per sentence is the simplest rule that keeps verification honest and keeps recovery short when something goes wrong. Apply it to text and action alike, including a sentence that only adds a note.
Test each command in a pair: one person speaks, one person watches. Ask the watcher to write down only what they see, not what they expected. Compare that note with the brief. A mismatch is a finding, and the conversation about it should happen after the test rather than during it. Run each command five times in a row before judging it. One clean attempt proves nothing, and one failed attempt may be a stumble rather than a design flaw. Five attempts give you a pattern you can describe and a pattern you can fix. Write the five results in a row so the pattern is visible without interpretation.
Pair similar commands deliberately. Put two commands that share a verb side by side and see whether the speaker can keep them apart under mild time pressure. Put two commands that share an object side by side and see whether the watcher can tell which one ran. These adversarial pairs expose weak design faster than a realistic task does, because they remove the context that normally helps a listener. Write the pairs that confused people into a short drill list. Drill them at the start of the next session before adding anything new. Keep the drill under three minutes so it stays part of the routine rather than a special event.
Record the exact wording of every failure. Paraphrase hides the cause; the phrase a person actually said is the evidence you need. Note whether the speaker paused, restarted, or changed the order. Note whether the watcher looked away or checked a different part of the screen. Keep the notes in the same file as the command library and date them. After a week, read the notes together and look for repeated shapes: the same verb, the same trailing value, the same object that nobody says in full. Repeated shapes are the design work. Bring the notes to the review, not a summary written after the fact.
End the test with a written revision, not a verbal one. Change one element per revision: the verb, the object, or the order. Rerun the same five attempts and compare. If the failure disappears, keep the revision and note the date. If it persists, change the next element. Do not combine two fixes in one round, because you will not know which one helped. This discipline is slower for a day and faster for a month, and it produces a command library with a history instead of a pile of opinions. Write the revision date beside the command so the history stays readable months later.
Install Voiskey on your Mac or Windows device and download it from the official page before the first design session. Press the shortcut in the app where the operator already works and speak a draft command. Watch the text appear at the insertion point and notice which parts of the sentence changed. The app removes filler words, stutters, false starts, and grammar slips, which is exactly the cleanup a command needs before an agent reads it. Keep a printed copy of the polished result beside the draft so the difference is visible to everyone in the room. Design decisions should be based on that visible difference, not on memory.
Teach the vocabulary during setup rather than after. Voiskey learns names, jargon, acronyms, and spelling preferences, so part numbers, internal tool names, and client codes can come through exactly as the team writes them. Add these terms in the first session and confirm the spelling on screen. A command that uses a term the app has not learned will drift, and the drift will look like a design flaw. Keep one list of agreed terms beside the command library and review it when a project introduces new names. Vocabulary is part of the command definition, not an afterthought. Give the list a version date and review it whenever a new project starts.
Use the app's adaptation deliberately. Voiskey adapts punctuation, formatting, tone, and word choice to what you are trying to do, and it can turn a spoken request into an AI-ready prompt with file names, paths, and commands. That means the same spoken sentence can arrive as a clean instruction for an agent or as readable prose for a colleague. Decide which output each command needs and write the choice in the brief. Then check that the polished result matches the choice. A command designed for control should read like an instruction, not like a sentence from a message. Check that distinction in the pair test, because the difference is easy to miss when you are speaking.
Plan for the team dimension early. Shared vocabulary and workflows help a group keep the same command names, and consistency across people is what makes a library usable. If colleagues speak different languages, the app supports more than one hundred languages and translation, so a draft can be reviewed in the reviewer's own language before it is adopted. Set one owner for the library and one review date per month. Shared tools without an owner drift into private variations, and private variations defeat the purpose of a written command set. Name the owner on the first page and put the review date beside it.
Review the library once a month with the operator and the brief in hand. Read each command aloud and ask whether it still matches the task described in the brief. Delete commands whose task has disappeared, and rewrite commands whose object has been renamed. Check that the vocabulary list still matches the terms used in the work. A library that nobody reads is worse than no library, because it creates a false sense of agreement. Keep the review under thirty minutes and record the decisions on the same page as the commands. The meeting is short because the preparation happened during the month.
Track two counts between reviews: commands added and commands retired. A library that only grows is usually collecting wishes rather than working tools. A library that only shrinks may be losing useful coverage. Aim for a rough balance over a quarter, and look at the reasons behind each change. Write the reason in one line next to the date. When the same reason appears three times, it points to a missing constraint in the brief. That is the moment to revise the brief rather than patch another command. Keep the reasons short enough to scan, and read them aloud before the review ends.
Test one old command each month as if it were new. Speak it five times in the pair format and compare the result with the brief. Commands decay when the surrounding work changes, and the decay is invisible to the people who use them daily. A monthly spot check catches the drift before a new operator inherits a broken phrase. Choose the command that was added longest ago, or the one that changed most recently. Both are likely candidates, for opposite reasons, and both are cheap to test. Put the result beside the command so the next review starts with evidence.
Publish the library where the work happens and keep the version date visible. Add a short changelog at the top so a reader can see what changed and why. Train new operators from the library rather than from personal habit, and ask them to mark anything that needs explanation. Their questions are the best signal that a command is not yet clear. Close the review by naming the next owner and the next date. A command library is a living document, and its quality is measured by whether someone new can use it without a private lesson. Keep the changelog to five lines and archive the rest.
Write the task, the person who performs it, the screen in front of them, and the result they need. Name the object that changes and the moment it should change, then add constraints such as available time and noise. Voiskey removes filler words and false starts, so the brief should also say which output the command needs: clean text or an instruction for an agent.
Voiskey removes filler words, stutters, false starts, self-corrections, and grammar slips, then adapts punctuation, formatting, tone, and phrasing to the task. It can turn a spoken request into an AI-ready prompt with file names, paths, and commands. The polished result is what a device agent can follow, and the operator can read it before anything runs.
Voiskey learns names, jargon, acronyms, and spelling preferences. Add each term once, confirm the spelling on screen, and keep the agreed list beside the command library. When a project introduces a new name, teach it before writing a command around it, otherwise the polished sentence may drift from the wording the team agreed to use.
One person speaks and one person watches, writing only what appears on screen. That separates the wording from the expectation and exposes a mismatch quickly. Voiskey works at system level, so the text lands at the insertion point in the app already in use, which means the watcher can compare the visible result with the written brief without switching context.

Download Voiskey for Mac and Windows and draft your first command brief with the app open.
Use it across macOS, Windows, iOS, and Android