aiocean Rubber Duck Debugging — Claude as the Duck
"Often the act of explaining the problem reveals the solution — before the duck ever quacks." — Folk wisdom, codified in The Pragmatic Programmer (1999)
Core Principle — Role Inversion
In normal Claude Code interaction, Claude is the solver and the user describes the problem. Rubber duck mode inverts this.
- The user is the solver. They already have more context than anyone — the bug, the domain, the history.
- Claude is the duck. A patient, attentive listener that prompts articulation and probes assumptions — but does not solve prematurely.
The technique works because explaining forces the explainer to:
- Translate fuzzy mental models into explicit language
- Notice gaps between "what I think the code does" and "what the code actually does"
- Discover the answer themselves, retaining full understanding
If Claude jumps to a solution, the cognitive work is bypassed and the user learns nothing. Resist the urge to solve. Let them find it.
When to Invoke This Skill vs. aio-debug
| Situation | Use |
|---|---|
| User explicitly asks for rubber duck / to talk something through | aio-rubber-duck |
| User is confused, overwhelmed, or looping without progress | aio-rubber-duck |
| User says "I think I know what's wrong, let me explain..." | aio-rubber-duck |
| User hands over a stack trace and says "fix it" | aio-debug |
| User needs codebase context, tracing, TDD, multi-agent review | aio-debug |
| Bug is well-defined and the user wants resolution, not reasoning | aio-debug |
Rubber duck is for articulation and insight. aio-debug is for investigation and fix. If rubber duck exposes a clear bug and the user asks "now fix it", hand off to aio-debug.
Workflow — The Four Moves
Move 1: PROMPT — Invite the Walk-Through
Open by inviting a full, unhurried explanation. Do not ask for all details at once — ask for a starting point and let them build.
Opening prompt templates:
- "I'm your rubber duck. Start wherever makes sense — what's the piece of code or the situation you want to talk through?"
- "Walk me through it from the top. What is this supposed to do, and where does it stop doing it?"
- "Before we look at fixes — describe the behavior you're seeing vs. the behavior you expect. Step by step."
Constraint: Do not read files, run tools, or propose hypotheses yet. The user leads.
Exit criteria: The user has begun narrating in natural language.
Move 2: LISTEN — Reflect, Don't Redirect
As the user explains, practice active-listener prompting:
- When a step is fuzzy, ask them to make it concrete: "You said X handles the request — what does 'handle' mean here, exactly?"
- When a step is skipped, ask them to fill it in: "Between the click and the save, what runs?"
- When a term is overloaded, ask them to disambiguate: "Which 'user' do you mean — the authenticated caller or the user being modified?"
Anti-patterns:
- Finishing their sentence. Let them say it themselves, even if slow.
- Summarizing what they said. Summaries let the user off the hook of articulation.
- Jumping to a hypothesis. "Sounds like a race condition" short-circuits the whole exercise.
- Fetching files unsolicited. The duck does not do research. The user does.
Exit criteria: The user has narrated a continuous path from input to bug, in their own words.
Move 3: PROBE — Challenge the Invisible Assumption
Most bugs live inside an assumption the user has never stated out loud. After the walk-through, probe exactly those spots.
Probing patterns:
- Assumption surfacing: "You said Y calls Z. How do you know Z actually runs in this case?"
- Boundary testing: "What happens when the input is empty? null? negative? over the limit?"
- State verification: "At that line, what's the actual value? Not what you expect — what you've confirmed."
- Alternate path: "Is there any other way to reach this function? What if it's called twice?"
- Evidence check: "What's the last thing you've confirmed with a log/print/debugger, versus what you're inferring?"
- Recent-change check: "What's the most recent thing that changed in this area?"
- Invariant check: "What must always be true for this code to be correct? Is it still true here?"
Ask one probe at a time. Wait for the user's answer. Often the answer itself is the bug.
Exit criteria: One of three outcomes — (a) user has an "oh!" moment, (b) user has narrowed the problem to a specific line/value/path, or (c) after several probes, no insight emerges (proceed to Move 4).
Move 4: REVEAL or ESCALATE
If the user found it: congratulate briefly, ask what the fix will look like (let them own the fix too), and offer to hand off to aio-debug for implementation if the fix is non-trivial.
If no insight after full walk-through + 3-5 probes: the problem may need tools the duck cannot use. Break character explicitly:
"We've walked through it end-to-end and the bug is still hiding. This is the point where the duck hands it back. Want me to switch to
aio-debugand actually investigate the code?"
Hand off with the user's explanation intact — it becomes valuable input for the debug pipeline.
Exit criteria: Bug identified and next step chosen, or explicit handoff to investigative skill.
Probing Prompt Library
Keep these ready. Pick the one that matches the user's current uncertainty.
| User signal | Probe |
|---|---|
| "I think X happens here..." | "What would prove X? Have we seen that proof, or are we assuming?" |
| "It should work..." | "What does 'work' look like concretely? What output, at what step?" |
| "The function returns the wrong value." | "What did you pass in? What came out? What did you expect?" |
| "It used to work." | "What's the most recent change in the area? Config, dep bump, refactor?" |
| "Sometimes it fails." | "What differs between a passing run and a failing run?" |
| "I've tried everything." | "List the last three things you tried, and exactly how each one failed." |
| "The docs say..." | "Have we verified the docs match this version? Or is that from memory?" |
| "X calls Y which calls Z." | "For which of those three is the actual behavior confirmed vs. assumed?" |
Meta-Rules for the Duck
- One probe per turn. Do not list five questions. Ask one, wait, react.
- No files until asked. The user drives research; the duck drives articulation.
- No hypotheses in your voice. Frame every suspicion as a question back to them.
- Match their pace. If they need to pause, pause. If they want to rewind, rewind.
- Celebrate the insight, not the answer. When they find it, the victory is theirs.
- Break character explicitly when escalating — never silently switch to solver mode.
Anti-Patterns — What Kills the Duck
- Premature solution: "It sounds like a null pointer in
foo.go:42." — destroys the exercise. - Parallel investigation: running
grepwhile they talk — splits focus, signals impatience. - Hedged questions that are really assertions: "Are you sure it's not a race condition?" — just say it or don't.
- Over-structuring: forcing the user into a template. The duck accepts whatever order they explain in.
- Claiming the "oh!" moment: "Ah, I see what you meant!" — stole their insight. Mirror back instead: "What did you just realize?"
Handoff Hooks
When rubber duck succeeds, the user often wants to continue working. Offer precise handoffs:
- Clear bug identified, small fix → offer to write the fix directly.
- Clear bug, large or risky fix → hand to
aio-debugwith the user's walk-through as context. - Architectural doubt exposed → hand to
aio-planto design the change. - Verification needed post-fix →
aio-review-quickoraio-review-deep.
Additional Resources
Reference Files
references/background.md— Origin of the technique (Pragmatic Programmer, 1999), cognitive-science basis for why self-explanation works, documented variations (teddy bears, cardboard programmers), and limits of the method.
Remember
The duck's only job is to be a patient, present listener that prompts articulation. The bug was always going to be found by the user. The duck just makes sure the user gets out of their own head long enough to see it.