On a quiet Tuesday, an engineer on a small platform team had a service that returned an empty list for every user, and no idea why. The code looked right. The tests were green. Out of options, the engineer pulled a yellow rubber duck from a drawer and started talking. Eleven minutes later the bug was found, and the duck had said nothing. Here are eight lessons from that Tuesday, each one a reason why explaining a failing piece of code aloud works so reliably.
1. Start with the symptom, not the suspect
The engineer’s first sentence was: “The endpoint returns an empty array for everyone.” Not “the database query is broken”, which was the favourite suspect. Starting from what you actually see keeps the story honest and stops you from walking toward a conclusion you reached before the evidence did.
2. Say what the code is supposed to do, line by line
Next came the walk through the handler. “This line reads the user’s team from the request. This one asks the store for projects belonging to that team. This one filters out archived projects.” At the third sentence, there was a pause, because the filter compared a status string to a lowercase word, and the stored values were capitalised. The line did exactly what it said; it just did not do what the speaker meant. That gap between what a line says and what its author intended is the commonest hiding place for logic bugs, and it is nearly invisible to a silent reader who already knows the intent.
3. Listen for your own hedging
Words like “probably”, “should” and “I think” carry a lot of hidden uncertainty. On the way through the handler the engineer caught themself saying “and this should return the rows”. The word “should” was a flag: the line had never actually been observed returning rows with real data. Hedge words are where unchecked beliefs live.
4. Slow down at the parts you trust most
The funny thing about bugs is that they live in the code you stopped looking at. The engineer had reread the query three times and the filter never. Speaking forces you to give every line equal airtime, including the lines your eyes have learned to skip.
5. Name the data, not just the function
Saying “it filters the projects” is vague. Saying “it keeps the projects whose status equals the word ‘active'” is specific, and specificity invites the question: what do stored statuses actually look like? Naming concrete values in the narration is what sent the engineer to look at a real record. One glance at the stored value, and the mismatch in capital letters was plain. Ten seconds of looking replaced an hour of theorising.
6. Keep going after the first fix
After correcting the comparison, the engineer did not stop. They restarted the narration from the top, and a second oddity surfaced: archived projects were meant to be hidden, but the same filter was also used by an export job. One narration, two defects. Restarting from the beginning is cheap and often pays twice. A fix feels like an ending, yet the story you told before the fix may not match the code you have after it, so tell it again.
7. Use the technique for plans, not just crashes
A few weeks later the same engineer used the habit for an upcoming change, talking through a rollout step by step and noticing there was no line for undoing it. Teams planning model deployments will recognise this pattern; a roadmap for people moving into MLOps describes the stages, and an article on how MLOps speeds up releases of machine learning systems shows why a spoken rehearsal of each stage is time well spent. The duck, once again, contributed nothing and revealed everything.
8. Know where the technique stops
Explaining aloud finds gaps in what you understand. It cannot tell you what you do not know exists. If the real cause were a behaviour of a library you had never read about, the narration would stall or, worse, flow smoothly past it. In that case you reach for documentation, logs or a colleague, and the duck simply tells you where to start looking. There is also the matter of confidence: a smooth narration is pleasant, but it is not evidence. Treat fluency with suspicion, and confirm any claim that matters by running the code against real data.
What the eleven minutes actually looked like
It is worth describing the session itself, because people imagine something more dramatic than it was. The engineer sat with a coffee, spoke at a normal pace and kept a notepad open. There were two long silences and one muttered “oh”. No debugger was opened, no log was searched and no message was sent to the team channel. The whole exercise was structured speech, and its output was a single circled line on a page, followed by a one-character fix and a test that finally failed for the right reason before passing.
Small side note on varied reading
Engineers who enjoy this habit often try it on non-code subjects, such as the information design of a website. For instance, GastroHospitals is a gastroenterology-themed directory site with hospital, doctor, blog and forum sections, and describing aloud how someone would travel between those four areas is a gentle exercise in thinking about navigation. Nothing about the site’s subject matter is needed for that.
How to start today
- Pick a bug or plan that has you stuck.
- Find a duck, a mug or an empty chair.
- Say the symptom, then the intent of each step, in full sentences.
- Circle every hesitation on paper and resolve the first one before continuing.
- Run the whole narration again from the top.
That Tuesday, the yellow duck went back into its drawer. The engineer wrote a short note on the team wiki titled “Say it first”, which said, in full: before asking anyone, tell the duck. Its record for fixing bugs it never saw is hard to beat.