Rubber Duck Debugging: Why It Works, an 8 Step Duck Script, and How to Keep the Explanation
Explain a stuck bug to a coworker and you often see it halfway through the second sentence. Rubber duck debugging gets you that moment on your own.
Rubber duck debugging means explaining a bug or a piece of code step by step, out loud, to a listener that knows nothing, traditionally a rubber duck. Saying what you expect and what actually happens, one step at a time, exposes the gap. The name comes from The Pragmatic Programmer (Andrew Hunt and David Thomas, 1999).
What rubber duck debugging is, and where the duck came from
In The Pragmatic Programmer, Hunt and Thomas tell of a programmer who carried a rubber duck and explained his code to it, line by line. The method is also called rubberducking or rubber duck programming, and Wikipedia has the history.
The duck is optional, and any silent listener works. In The Practice of Programming (1999), Kernighan and Pike describe a university help desk where students had to explain a bug to a teddy bear before a human would help.
MIT OpenCourseWare has a two minute short and the longer cut below.
Why explaining a bug out loud finds it
Talking turns a vague feeling into claims you can check. A brain dump done by talking uses the same move on a head full of open loops.
You have to say what you expected, not only what you see
Explaining code makes you say what it should do, not just what it does. Say "this returns the open orders" and you may notice nothing filters by status.
Speech goes one step at a time, so you cannot skip the step you "know" works
Your eyes jump to the line you suspect. Your mouth cannot, so you narrate the boring step you were sure about, which is often where the bug lives.
The listener knows nothing, so every assumption has to be said
A colleague nods along at "then the cache is fresh." A duck does not, so the assumption becomes a sentence you can test.
What the evidence does and does not say
Duck research is thin. In a 2023 study of 101 people thinking aloud, a listening robot helped no more than a giant rubber duck.
The closest support is the self explanation effect. In Chi, de Leeuw, Chiu and LaVancher (1994) in Cognitive Science 18(3), students prompted to explain a biology text to themselves understood it better.
That is learning research, not debugging, so it is only indirect support for the rubber duck theory. Claims about "different neural pathways" rarely cite anything; the three mechanics above are a simpler explanation.
The duck script: an 8 step checklist
Most guides say "go line by line," which breaks down in a large codebase. Walk the data path instead: follow one input to where it comes out wrong.
- Say the expected behavior in one sentence.
- Say the actual behavior with exact evidence: the error text, the wrong value, the log line.
- Say the smallest input that reproduces it.
- Walk the path from input to output, one step per sentence. Name the real value at each step, not the value it should have.
- Say each assumption as "I am assuming X, and I know it because Y." If there is no Y, that is your next check.
- Say what you have already ruled out, and how you ruled it out.
- Listen for trigger words like "obviously," "it just," "should" and "somehow." Stop there and check.
- Say the single next check you will run.
A worked example: one bug, explained out loud
An illustrative example, not a real incident: a store dashboard's "today's orders" count misses orders placed after 5 pm Pacific on a July evening, and they appear the next day.
Expected: every order placed today, Pacific time, counts toward today. Actual: orders after 5 pm are missing tonight and appear tomorrow. Smallest repro: one test order at 5:10 pm.
Walking it: the order is saved with a created_at timestamp. The dashboard asks for orders where the date of created_at equals today, July 10.
I'm assuming created_at is in local time... wait, how do I know that? I don't.
It's stored in UTC. So 5:10 pm Pacific on July 10 is 00:10 UTC on July 11. The date part says July 11, so the order drops out of today.
Ruled out: the order saves, and the query runs. In winter the cutoff would move to 4 pm, since Pacific is then eight hours behind UTC. Next check: build the day boundaries in the store's time zone.
The fix: compute today's start and end in the store's time zone, convert both to UTC, and select orders between them. Step 5 caught it: the assumption had no "because."
How to rubber duck in an open office or on a call heavy day
- Whisper or mouth the words. The step order still holds.
- Type it out in a draft PR description. As Coding Horror notes, people often solve their problem while writing a careful question.
- Take 10 minutes alone, in an empty room or on a walk, and speak into a voice note. At your desk, talk to text on your computer works too.
- Mute between calls and say the script.
| Duck option | Works with people around | Leaves a record | Watch out for |
|---|---|---|---|
| Talking to a duck | Not really | No | Feeling silly and rushing |
| Whispering | Yes | No | Skipping boring steps |
| Typing it out | Yes | Yes | Dropping the "because" parts |
| A colleague | Yes | Rarely | Nodding past steps |
| An AI chat | Yes | Yes | Skipping expected versus actual |
| A voice note | In a quiet spot | Yes | Saying secrets out loud |
Rubber duck debugging with AI: when a chat helps and when it skips the insight
When it helps: an AI chat makes a decent rubber duck debugger after you have done steps 1 to 5, when the library or error is new to you, or when you make it ask the questions:
"Act as a rubber duck. Do not suggest fixes. Ask me one question at a time about what I expect and what I observe."
When it skips the insight: paste the stack trace first and you get a plausible fix before you state expected versus actual. You never find the wrong assumption, and the fix may hide the root cause. Paste your spoken explanation, not just the error.
Pasted code and logs fall under your employer's policy, so strip secrets and customer data first. For long prompts, try dictating into ChatGPT and reading it before you send.
Keep the explanation: it is most of your PR description
After the fix, the explanation usually evaporates, yet it holds most of what a reviewer needs. Pull request templates ask for the same parts.
| What you said to the duck | PR description section |
|---|---|
| Expected versus actual | Problem |
| The "wait" moment | Root cause |
| What you changed | Fix |
| The smallest repro | How to test |
| What you ruled out | Notes for reviewers |
A commit body is the same "why," only shorter; the git commit docs suggest a summary line, a blank line, then detail.
Write it right after the fix, or record the duck session as a voice note and condense it later. Type identifiers and file paths yourself; voice coding explains why dictation mangles them.
Doing this with VoiceSnap Pro
Put the cursor in a PR description box, a ticket, or a commit message in your editor. Hold Right Option on Mac or Right Alt on Windows, speak, and release. VoiceSnap Pro types punctuated text at the cursor.
- Personal vocabulary covers service names and team acronyms.
- The Paste last dictation shortcut recovers text that did not land.
- For the duck session, voice notes use Right Command (Right Ctrl on Windows) or Control+Option+N (Ctrl+Alt+N). The note keeps its recording unless you change Keep recordings. Summarize turns the monologue into a draft, and notes export as Markdown.
On privacy: audio goes encrypted to VoiceSnap's server and on to OpenAI for transcription, and dictation audio is then discarded. The Clean up dictation setting, on by default, sends the transcript (never the audio) of a dictation or voice note of up to about five minutes to OpenAI to remove filler words, repeats and corrected slips; AI actions, AI titles and AI tags send text there too. Each of these can be turned off in Settings.
Nothing you say trains AI models, but never say secrets or customer data aloud. See privacy and data, and zero data retention for what retention terms mean.
VoiceSnap Pro runs on Macs with Apple silicon and macOS 13 or later, and 64-bit Windows 10 21H2 or Windows 11. Every new account can try every feature free with 5,000 transcribed words and 50 manual AI actions, given once with no expiry and no card required. Creating, editing and organizing notes has no free-plan cap. Pro is $9 a month for unlimited transcription and manual AI actions, subject to fair use, on up to 3 devices. Download free for Mac or Windows. Automatic AI titles, tags and reminders set by voice do not count as manual AI actions.
When the duck will not help
- You do not know what the code should do. That is a requirements problem.
- It is someone else's code and you cannot state their intent.
- The problem is environmental, like flaky infrastructure. You need logs and metrics, not narration.
Time box it: after two passes with no answer, ask a person and paste the script output as your question.
Frequently Asked Questions
Is rubber duck debugging still relevant?
Yes, even with AI coding assistants. Stating expected versus actual before you ask one is what finds the wrong assumption.
What does it mean to rubber duck code?
It means explaining your code or bug step by step to a listener that knows nothing, until the gap between expected and actual shows up.
Why is it called rubber duck debugging?
It comes from a story in The Pragmatic Programmer. Rubber ducky debugging and rubber duck coding mean the same thing.
Does it work if you write the explanation instead of saying it out loud?
Yes. Writing keeps the step order and leaves a record for your PR. Speaking is usually quicker: conversation runs near 150 words per minute, while the average typing speed is about 52 (general figures).
What are the most common rubber duck debugging mistakes?
Going line by line instead of following the data path. Saying what a value should be instead of what it is. Pasting the error into an AI chat before stating expected versus actual.
Try the script on your next bug
Say the 8 steps before you ask anyone, then keep the explanation: it is your PR description, nearly written.
