Rubber-Duck Notes That Unlock Stuck Debugging. A Build Next Stack field guide for learners shipping small projects.
Duck notes are not diary entries
Rubber-duck debugging fails when the duck receives venting instead of facts. A duck note is a structured memo you write before asking chat, forums, or a friend. It excludes feelings except confused at step X because confusion locates the gap.
One duck note per stuck session. Filename pattern: duck-YYYYMMDD-short symptom.md. Diaries sprawl; duck notes fit one screen so you actually reread them before posting elsewhere.
Ben renamed venting files to duck notes and cut average time-to-fix for recurring API bugs because Expected/Actual exposed wrong assumptions faster than chat threads.
Template: expected actual tried next
Copy this skeleton every time:
- Expected: clicking Save writes row to database and returns 200
- Actual: 200 returned but row missing; network tab shows empty body
- Tried: logged payload — undefined userId; added guard — still empty
- Next: inspect middleware stripping body on OPTIONS preflight
Fill Expected and Actual before Tried. Most skips happen because Tried becomes random button presses. Expected forces you to name correct behavior independent of your code.
Next is one step, not a plan essay. One step keeps momentum; plan essays become procrastination.
Ben sets a five-minute timer for Expected/Actual only—no Tried until both are written. Skipping the timer invited rambling Actual paragraphs that hid missing reproduction steps.
He keeps a text expander snippet duck that inserts the four headings—zero friction beats good intentions when the console is red.
Voice memo when typing slows you
If typing stalls, record sixty seconds explaining Expected and Actual to your phone. Transcribe roughly into the template. Speech bypasses the inner critic that deletes sentences before they clarify.
Delete the audio after transcription unless tone matters—rare in debugging. The text template is the artifact; audio is scaffolding.
Voice memos shine when the bug involves UI timing—you describe clicks better than you type them.
Transcribe within an hour while memory is warm; next-day transcription invents details that send you down wrong Next steps.
Share duck notes without shame
When you ask for help, paste the duck note, not a apology paragraph. Helpers answer faster when Expected/Actual/Tried/Next are visible. Shame paragraphs hide missing reproduction steps.
Redact secrets inline—replace API keys with REDACTED, keep structure intact. A clean duck note respects helper time and models good bug reports for future teammates even if you are solo today.
If nobody helps, the note still works tomorrow when fresh eyes are yours after sleep.
Ben posts duck notes to a private repo wiki before public forums—same structure, less performance pressure. Structure travels across audiences.
Link duck notes to git commits
After the fix, add one line at the bottom:
Fixed in commit abc123 — body parser order wrong.
Link note from commit message: see duck-20260724-empty-body.md. Future search connects symptom story to diff. Error journal gets a one-line summary; duck note archives detail.
Linked notes turn debugging into searchable institutional memory for a one-person shop.
Ben adds Environment line when bugs are env-specific—staging only, M1 local repro fails—so future searches do not chase fixes that only applied on one machine.
When the duck fails switch layers
If three Next steps in one note all failed, switch layer explicitly:
- UI event → network request
- Network → server handler
- Server → database row
- Database → permissions or migration
Write the layer switch as a new duck note section header—Layer: network—instead of mixing stories. Layer switches beat restarting from zero because Expected/Actual from the previous layer stay visible.
When the duck fails entirely, take a walk and return to Expected only—often Expected was wrong, not the code.
Wrong Expected example Ben caught: Save writes on click when spec actually deferred save until blur. Rewriting Expected made the bug disappear without code changes.
From duck note to pull request description
When the fix lands, paste duck note into PR description with light editing:
- Keep Expected/Actual for reviewers
- Collapse Tried into bullet list of rejected paths—saves review debate
- State fix in one line linking commit
Ben’s PRs with duck skeletons merged faster on solo projects when he asked async review—reviewers saw dead ends he already eliminated.
Store duck notes in docs/ducks/ or a top-level folder; link from PR. Future contributors inherit debugging context, not just diff.
Delete ducks that describe typos or one-line fixes—over-archiving noise hides signal when search returns fifty files.
When AI chat helps after a duck note, paste the final cause line back into the duck file so human and automated help share one paper trail.
Ben reviews closed ducks monthly for Actual lines that repeat—those become integration tests or lint rules so the duck does not re-quack the same story.
Empty Tried sections mean you skipped experimentation—if Next failed instantly, write what you observed in one line before moving on.
Open a duck note before the next bug hunt
On your next stuck bug, create the template file before opening search or AI chat. Fill Expected and Actual with timestamps if timing matters. Stop after writing Next—even if Next is a guess—and attempt that one step. Most ducks quack before step three.
Debugging skill is partly documentation skill. Duck notes make both faster without pretending the rubber duck was ever magic.
Pin the template in your editor snippets or a sticky note beside the monitor. Friction to start the note is the main reason people skip the duck and jump straight to random fixes.
After three resolved bugs, search your ducks folder for repeating Actual patterns—that repeat is your next error journal tag.
Teach the template to future collaborators in CONTRIBUTING.md—one screen of Expected/Actual/Tried/Next beats pages of style guide for bug reports.
Start the next debugging session by reading yesterday’s duck note aloud—even solo, hearing Expected/Actual catches stale assumptions before you touch the keyboard.
The duck is cheapest before the tab spiral—sixty seconds of structure saves sixty minutes of random diffs.