Clavio for Mac: six spoken briefs for coding assistants

Clavio for Mac: six spoken briefs for coding assistants

"Make the form work better" is easy to say. It is much harder to implement: better validation, a different layout, and clearer loading feedback are three different tasks. A useful spoken brief gives the assistant something it can inspect and something you can verify. Start with four landmarks: goal, context, constraints, and done when.

I'm Stas, director of Just Tools LTD, the company behind Clavio, an AI dictation app for Mac. Below are six structures you can use with Clavio, another dictation tool, or a keyboard. The examples are illustrative tasks, not customer results. See voice input in action - this short Claude demo shows dictation and optional automatic sending. For the coding tasks below, keep the brief visible, review it, and send it when you are ready.

1. Report a reproducible bug

Structure:

• When I…
• I expect…
• Instead…
• Reproduce it by…
• Keep…
• Fixed means…

Example:

When I submit an empty comment, I expect a validation message. Instead, the submit button stays in its loading state. Open a post, leave the comment empty, and press Send. Keep the existing API response format. Fixed means the message appears and the button can be used again.

Give the assistant a trigger and an observable failure. Paste the exact error message afterwards if you have one. Saying "there is a network error" loses information that a status code or stack trace might contain.

2. Request a small feature

Structure:

• The user needs…
• Put it in…
• It should…
• Preserve…
• Ready means…

Example:

The user needs to copy a support reference from the error panel. Put a copy button beside the reference. Show a short confirmation after copying. Preserve normal text selection. Ready means the button works with a keyboard, the copied value matches the reference, and a failed copy does not show success.

Keep the request centred on one user action. The last condition matters: a visual confirmation should reflect what happened, rather than appear whenever a button was pressed.

3. Ask for a focused review

Structure:

• Review…
• Focus on…
• For each finding, explain…
• For now…

Example:

Review the changes to comment submission. Focus on duplicate requests and failed retries. For each finding, explain the trigger, the user-visible result, and the relevant code. For now, report findings before changing files.

That final sentence defines the output you want. If the task is diagnosis, say so. Otherwise a review can quietly turn into a larger implementation task.

4. Describe a bounded refactor

Structure:

• The repeated logic is…
• Simplify…
• Preserve…
• Avoid…
• Check…

Example:

The loading-state logic is repeated in three settings panels. Extract shared state handling where it improves readability. Preserve each panel's error messages and public interface. Avoid a new dependency. Check saving, retrying, and closing a panel while a request is in progress.

A refactor needs a behaviour boundary. Name what must stay true, and let the assistant inspect the code before deciding what can reasonably be shared.

5. Request a test for a failure mode

Structure:

• Protect against…
• Start with…
• Trigger…
• Assert…
• Also cover…

Example:

Protect against losing a draft after a failed save. Start with an edited draft, make the save request fail, and assert that the text remains available for another attempt. Also cover a successful retry. Use the project's existing test tools.

This describes the failure the test should catch. It gives more direction than "add tests" without prescribing the test's internal implementation.

6. Prepare a PR description

Structure:

• The problem was…
• The change now…
• Scope is…
• Checks completed were…
• Still uncertain is…

Example:

The problem was that the save button stayed disabled after a network failure. The change restores the button and keeps the draft. The scope is the editor's retry state. The completed check was a manual failed-save and successful-retry sequence. Automated checks have not been run yet. Only include validation that happened. If you cannot remember whether a check passed, verify it before putting it in the description.

The review pass matters as much as the template

Read the resulting brief once before sending it. Check four details:

• Names: Are file, function, and service names correct?
• Numbers: Did a timeout, version, or limit survive accurately?
• Negations: Did "do not change the API" keep the "not"?
• Stopping point: Is it clear whether the assistant should investigate, edit, or report?

Type or paste exact identifiers and symbols when that is easier. Speaking the explanation and typing a function name is a useful combination.

Here is a simple check for your next task: could someone read the final instruction and tell whether the result satisfies it? If "done" still means "make it nicer," add one observable condition.

Using the briefs with Clavio on Mac

For a first coding brief, focus the assistant's message field and start with Hold key. Use Clean if you want punctuation and filler cleanup while keeping the wording close. Leave After paste set to None so the result stays visible for review.

Clavio's general Polish settings. This screenshot shows the available controls; Tidy is selected here. For the first coding brief above, choose Clean.

An app profile lets you keep a technical writing style for Claude and a more conversational tone for email. Listening modes can differ too: for example, a wake phrase in Claude and Hold key in your email app. Listening and pause controls inside an app profile. This example inherits the global listening mode; the same panel offers app-specific choices.

Clavio also offers wake-word and Always On modes, with app-specific settings. Its per-app style, tone, and pause controls are listed under Pro. The free allowance of 3,000 polished words per month does not make every advanced control free.

Clavio requires Apple Silicon and macOS 14.2 or later; ordinary transcription and polishing use online processing. You can check the current features and plans on the Clavio website.

Which detail do you most often have to add to a coding task after the first attempt: context, constraints, or the definition of done?

AI disclosure: This article was drafted with AI using my product notes. The task examples are illustrative.