A practical way to turn bug facts into a clear spoken report, a fix, and a test

Describing a Bug Out loud is only useful if you start from facts rather than from a theory. Before you speak, collect five things: the screen or feature, the exact steps you took, what you expected, what happened instead, and whether it happens every time. Write them as five short lines, not as a paragraph. A theory is welcome later, but it should not be the opening. The facts give the agent a target, while a theory gives it a direction that may be wrong. Start with the facts and the agent will often find the cause faster than you would.
Reproduce the bug at least twice before you describe it. The first run tells you what happened; the second tells you whether it is consistent. Note any difference between the runs, such as timing, a different input, or an extra click. A bug that appears only once is often a different problem than a bug that appears every time, and the two need different descriptions. If you cannot reproduce it, say so explicitly and describe the conditions you remember. An honest cannot reproduce is far more useful than an invented sequence that sends the agent down a false path. Consistency is the first fact worth establishing, and it is cheap to get.
Capture the smallest input that triggers the problem. Reduce the case until removing any further detail stops the bug from appearing. The smallest input makes the description precise and the eventual fix easier to verify. Write it down exactly, including the odd characters, the long name, or the empty field. If the input is too large to speak, paste it and describe its shape in one sentence. A reduced case is a gift to everyone involved: to the agent that has to reason about it, and to the reviewer who has to confirm the fix later. Reduce until the bug disappears, then step back one detail.
Note the environment only where it changes behavior. A bug that appears at one window size and not another, or with one set of content and not another, is a different bug from one that appears everywhere. Record the condition and say whether you tested the alternative. Avoid listing every version number you know; list the ones you changed during the reproduction. The goal is a description in which every line either narrows the cause or proves the effect. Facts that do neither can wait until the fix is under discussion. Every line earns its place by narrowing the search.
Speak the reproduction as a numbered sequence of actions, one action per sentence. Open the settings screen. Choose the second tab. Enter a long name. Press save. This is easier to follow than a narrative, and it makes a missing step obvious. Say the sequence at a steady pace, and pause between steps so the app can punctuate. If the sequence has a branch, say which path you took and which one you skipped. A numbered reproduction is the backbone of a useful bug report, because it can be followed exactly and repeated later. Numbered actions survive the cleanup step and survive a retelling.
Include the starting state before the first action. A form that is already half-filled behaves differently from one that is empty, and the agent cannot see your screen history. Say the form had one saved item and the second tab was already open. The starting state is one sentence and it prevents a long round of clarification. When the state is complicated, describe the minimum path to reach it rather than every prior action. The goal is a starting point someone else can reproduce in under a minute. A precise starting point is half of a reproducible sequence. That saves a round trip.
Keep the reproduction free of diagnosis until the sequence is complete. Do not say the save handler is probably dropping the value until you have described what you did and what you saw. A diagnosis placed early anchors the agent to one explanation and may hide a simpler cause. After the sequence, add your theory as a clearly labeled sentence: one possible cause is the save handler. The label matters, because it tells the agent the theory is separate from the facts. This ordering keeps the investigation honest and open. The facts should be complete before the theory begins. Order matters here.
End the sequence with the exact moment the problem appears. Say after pressing save, the row shows the old name instead of the new one. Naming the moment gives the description a clear boundary and tells the agent where to focus. It also makes the expected and actual behavior easy to state in the next turn. If the problem appears at several moments, describe the first one and note the others. A reproduction without a clear moment of failure is a story without an ending, and stories without endings invite the wrong fix. A named moment turns an anecdote into a testable report.
Describe expected and actual behavior side by side, using the same wording for both. If the expected sentence is the row shows the new name, the actual sentence should be the row shows the old name. Parallel wording makes the difference visible and prevents the agent from misreading which part is the problem. Say expected first, then actual, then the difference in one clause. This structure is short and unambiguous, and it works for visual, behavioral, and error-message bugs alike. Parallel sentences are the fastest way to show a difference, and the safest way to keep it visible. Keep them adjacent.
Be specific about what you expected, and say where that expectation comes from. An expectation from the design, from the previous version, or from a written requirement carries different weight. Say the design shows the new name, so the row should update. The source of the expectation tells the agent whether to preserve current behavior or change it. Without a source, the agent has to guess whether your expectation is a requirement or a preference. A single clause naming the source removes that guess. A named source turns a preference into a requirement the agent can act on clearly. Say it plainly.
Describe the actual behavior without exaggerating it. If the row shows the old name, say that, not that the save is completely broken. Exaggeration pushes the agent toward a large fix, while a precise observation supports a small one. Include what still works, such as the row does update after a refresh. Noting the working parts narrows the cause and prevents a fix that changes more than necessary. Accurate observation is what makes a bug report actionable rather than alarming. Precision keeps the eventual fix proportional to the actual problem rather than to the alarm it caused for everyone. Stay literal.
Add one sentence about the impact, and keep it factual. Say the stale name confuses users who rename items often, or say the wrong total appears on the summary screen. Impact helps the agent and the reviewer prioritize, but it should not replace the technical description. Keep it to one sentence and place it after the expected and actual statements. A report that leads with impact and buries the behavior is harder to act on, while a report that states behavior first and impact second is easy to triage and easy to fix. Behavior first, impact second, is the order that triages cleanly.
Ask for a fix and a test in the same request, but describe them as two deliverables. Say fix the save path so the row shows the new name, then add a check that fails when the old name remains. Naming both prevents the agent from returning a patch with no way to confirm it. If you use Voiskey, speak the two deliverables as separate sentences at the insertion point, and the app will keep them distinct in the transcript. A fix without a check is a hope; a fix with a check is evidence. Two named deliverables are two things you can check at the end.
Specify the test at the level you can actually verify. A test that reproduces the original sequence is ideal, because it fails before the fix and passes after. A test that only checks the final value is still useful, but say so. When the project has an existing test suite, ask the agent to follow its conventions so the new test fits. When it does not, ask for a small, readable check that a person can run by hand. The test should be something the next person can trust, not a formality attached to the patch. A test you can run by hand is a test you will actually run.
Ask for the smallest fix that addresses the described cause. A bug report that asks for a redesign invites a large change; a report that asks for the smallest change that makes the check pass keeps the diff reviewable. Say keep the existing structure and change only what the check requires. If the agent proposes a broader change, ask why the smaller one would not work before accepting it. This habit keeps a simple bug from turning into an unplanned refactor and keeps the review focused on the actual problem. A small fix is a fix you can explain in one sentence.
Record the request and the response next to the bug facts. When you download the latest Voiskey build, rerun the same reproduction and the same check against the new version, so the comparison stays valid across a tool update. Keep the original expected and actual sentences unchanged, and write the new result beside them. This record is what lets you say the fix works without relying on memory. It also tells the next person whether a later regression is new or a return of something that was already fixed once. The record makes the next comparison a matter of reading, not remembering.
Confirm the fix by replaying the exact reproduction, not a simplified version of it. Run the numbered steps in order, use the smallest input, and check the moment where the problem appeared. Then try the case that previously worked, to make sure the fix did not break it. A fix that passes the original case and fails a neighbor is not ready. Replaying the exact sequence is the only way to know, and it takes less time than a second round of bug reports. The original sequence is the contract, and the neighbor case is the safety check. It is the whole review.
Check the test as carefully as the behavior. A test that passes for the wrong reason is worse than no test, because it creates false confidence. Read what the test asserts, run it against the unfixed code if possible, and confirm that it fails there. If you cannot run it against the old code, ask the agent to explain why the test would have failed before the fix. A test that would have passed before the fix proves nothing about the bug, and it will not protect you from a regression later. A test that cannot fail has no power to protect you.
Close the report with a short summary of cause, fix, and check. Write what the cause turned out to be, what changed, and which check now covers it. Keep the original facts and the final result in the same place so the record reads as one story. If the cause was different from your theory, say so; that detail is often the most useful part for the next investigation. A closed report with a clear cause is a reference, while a closed report with only a status is a dead end. A story with a cause is worth more than a status with a date.
Decide whether the bug deserves a broader follow-up. A single stale label may only need the fix, but a pattern of stale values across several screens may point to a shared cause worth a separate task. Note the pattern without expanding the current fix. If a follow-up is needed, open it with its own reproduction and its own check. Closing the report means the described bug is fixed and verified, not that every related question has been answered. Keeping those two things separate is what keeps a bug queue honest. Separating the two keeps the queue clean and the report honest.
Voiskey is a system-level voice typing app. Press a shortcut and speak the bug facts, the reproduction, and the expected versus actual behavior, 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 report reads as a clean, specific sequence instead of a rambling account.
State the screen or feature, the exact steps you took, what you expected, what happened instead, and whether it happens every time. Write them as five short lines before you speak. Reproduce the bug twice and note any difference between the runs. These facts give the agent a target before any theory is offered.
Yes. Speak the expected sentence first, then the actual sentence using the same phrasing, then name the difference in one clause. Voiskey places both at the insertion point in your editor and removes filler words, stutters, false starts, and self-corrections, so the two sentences stay parallel. Parallel wording makes the difference visible and prevents the agent from misreading which part is wrong.
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 you can describe the steps in the language that comes naturally.

Download Voiskey for Mac and Windows and describe the next bug out loud.
Use it across macOS, Windows, iOS, and Android