rubber-duck
Skill6 starsChanged 34 days agoMITView on GitHub
Rubber duck debugging and claim-walking. Use when a user is stuck on a bug ("I don't understand why this isn't working", "talk me through this bug", "rubber duck", "stuck", "doesn't make sense", "help me think") or has been debugging 20+ minutes without progress. Also use, with no human in the loop, to walk the claims in a PR description or design doc against the actual code ("author claims...", "walk the design", "design for #N, answer your own questions from evidence"), or any time an agent is about to assert how code behaves without having checked. Interactive mode questions the person; autonomous mode answers each question from evidence (file:line, command output) and returns a claim / evidence / verdict table.
24 other projects use a version of this.
Adopted by
Most recently taken up by
- n1kben/agentstheir own version, first seen Nov 16, 2026
- jingyibuilds/rubber-ducktheir own version, first seen Nov 15, 2026
- draekien/skillstheir own version, first seen Nov 15, 2026
- Osipchuk/agent-skillstheir own version, first seen Nov 8, 2026
- jsleemaster/gooblintheir own version, first seen Nov 1, 2026
- damacus/agent-skillstheir own version, first seen Oct 29, 2026
Used with
Projects with it also use caveman, grill-me and 4 more.
Other files people use alongside this one.
Files found in the same public projects as a version of this one, more often than they turn up anywhere else. Each project counts once, large collections count for less, and this file's own repository is left out.
MicrosoftSkillcaveman
Ultra-compressed response style that reduces output token count while preserving technical accuracy, with intensity levels and auto-clarity safety rules
Also in 3 projects that use this
GoogleSkillgrill-me
A relentless interview to sharpen a plan or design.
Also in 5 projects that use this
MicrosoftSkillhandoff
Compact the current conversation into a handoff document for another agent to pick up.
Also in 5 projects that use this
GoogleSkillprototype
Build a throwaway prototype to answer a design question. Use when the user wants to sanity-check whether a state model or logic feels right, or explore what a UI should look like.
Also in 3 projects that use this
- +2 more from google
Other versions24 projects use a version of this.
Word for word · 0
None found.
Edited · 0
None found.
Wrote their own version · 24
- kirodotdev/KiroCrew★ 4.8ksame name
- thoughtbot/rails-consultant★ 29same name
- jim60105/copilot-prompt★ 22same name
- stevepolitodesign/skills★ 10same name
- jmcelreavey/devhub★ 5same name
- oneafrikan/the-grid★ 5same name
- Osipchuk/agent-skills★ 5same name
- stormlightlabs/thunderus★ 4same name
- dfrysinger/skills★ 3same name
- jsleemaster/gooblin★ 3same name
14 more not listed
How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.
In this repository79 other files it gives its agents.
- adr-phase-coverageSkill
- aposd-red-flag-reviewSkill
- apple-on-device-aiSkill
- artifact-gatesSkill
- asc-app-create-uiSkill
- asc-build-lifecycleSkill
- asc-cli-usageSkill
- asc-crash-triageSkill
- asc-id-resolverSkill
- asc-localize-metadataSkill
- asc-metadata-syncSkill
- asc-notarizationSkill
- asc-ppp-pricingSkill
- asc-release-flowSkill
- asc-revenuecat-catalog-syncSkill
- asc-shots-pipelineSkill
- asc-signing-setupSkill
- asc-submission-healthSkill
- asc-subscription-localizationSkill
- asc-testflight-orchestrationSkill
- asc-wall-submitSkill
- asc-workflowSkill
- asc-xcode-buildSkill
- choose-boring-technologySkill
- ci-preflightSkill
- conways-lawSkill
- cost-routingSkill
- cost-tier-routingSkill
- cunninghams-lawSkill
- ddd-strategic-auditSkill
- ddd-tactical-reviewSkill
- debug-test-captureSkill
- developing-ios-appsSkill
- doerrs-lawSkill
- fitts-lawSkill
- fix-regression-guardSkill
- galls-lawSkill
- goodharts-lawSkill
- greenspuns-tenth-ruleSkill
- gsd-core-hooksSkill
- hofstadters-lawSkill
- hyrums-lawSkill
- ios-accessibilitySkill
- ios-simulator-boot-healthSkill
- kerckhoffs-principleSkill
- kernighans-lawSkill
- knuths-optimization-principleSkill
- lady-lovelaces-objectionSkill
- leaky-abstractionsSkill
- linuss-lawSkill
- mobile-ios-designSkill
- money-boundary-judgmentSkill
- moores-lawSkill
- no-deferSkill
- norvigs-lawSkill
- parkinsons-lawSkill
- peter-principleSkill
- postels-lawSkill
- post-fix-traceSkill
- qa-test-architectSkill
- The first 60 shown.
The file
Show its rules and text
We split this skill into the rules it gives an agent
19 rules. 0 are common, 18 are distinctive, and 1 is very specific to this project.
0
Common
Most of the 24 edited versions we read keep these.
18
Distinctive
This author's own choices. Worth a look.
1
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 45
Surface assumptions, don't answer them: When you hear one, name it: "You just assumed X — is that definitely true?"
- Distinctive: line 47
The moment explaining stops flowing is the moment: When the human hesitates, backtracks, or says "...well, it should..." — that pause is …
- Distinctive: line 55
Ask the human to state the bug in one sentence.
- Distinctive: line 59
If they can't state it in one sentence, the problem isn't well-understood yet.
- Distinctive: line 65
Do not look at code yet. Get:
- Distinctive: line 71
If "sometimes" or "only when": that condition is almost certainly the bug's domain.
- Distinctive: line 77
Before touching code, ask:
- Distinctive: line 129
When you find it, name it:
- Distinctive: line 133
Do not solve it. Name the contradiction.
- Distinctive: line 145
When this happens: stop talking.
- Distinctive: line 151
After the human has identified the root cause:
- Distinctive: line 153
Ask them to re-state the bug in one sentence — including the actual cause, not just the symptom.
- Distinctive: line 155
If yes: they're ready to write the fix.
- Distinctive: line 161
Use when no human can answer.
- Distinctive: line 170
All three reduce to the same thing: a numbered list of checkable statements.
- Distinctive: line 174
Write each claim as one line a stranger could check ("4xx errors are never retried", not "error handling is robust").
- Very specific: line 188
Look specifically for the places claims usually break: boundaries (off-by-one in counts), ordering (delete-then-write races), paths the …
- Distinctive: line 203
Do not propose fixes until at least one claim is REFUTED, and then only after the table.
- Distinctive: line 235
After each session, note:
“Common” is measured: kept by at least 6 in 10 of the 24 edited versions of this file we could read. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Rubber Duck Debugging
Core Principle
The bug lives in the gap between what you think the code does and what it actually does.
You can't see that gap from inside your own head. Explaining to an external listener — even a silent one — forces you to reconstruct your mental model from scratch. That reconstruction is where the bug surfaces.
The AI duck has one advantage over a physical duck: it notices when an explanation is internally inconsistent, when an assumption sounds shaky, or when a critical step was skipped.
Pick a Mode First
| Situation | Mode |
| A person is present and stuck | Interactive (the protocol below) |
| Args say "autonomous", "walk it", "author claims", "answer your own questions", or there is no one to reply | Autonomous (see "Autonomous Mode") |
Why two modes: the interactive duck works because the human must reconstruct their mental
model. An agent has no one to reconstruct for, and an agent asking itself questions and
answering from memory just repeats its own fluent guess. Research on self-correction found it
helps only when the check is grounded in something external: code execution, tests, tools
(Huang et al. 2023, arXiv 2310.01798). So in autonomous mode every question is answered by
an observation, not an opinion. Sources: docs/research/rubber-duck-skill-improvements.md.
Rules for the Duck (interactive mode)
- Never jump to solutions. The duck's job is to keep the human explaining, not to fix the bug.
- Never accept hand-waving. "...and then it processes the data..." is not an explanation.
- Surface assumptions, don't answer them. When you hear one, name it: "You just assumed X — is that definitely true?"
- Ask "why" not "how". "How does it get the user ID?" is implementation. "Why do you expect that value to be set at that point?" is root cause.
- The moment explaining stops flowing is the moment. When the human hesitates, backtracks, or says "...well, it should..." — that pause is the bug's address.
The Session Protocol
Step 0: Before Anything Else
Ask the human to state the bug in one sentence. Not symptoms. Not what they tried. One sentence:
"What do you expect to happen, and what happens instead?"
If they can't state it in one sentence, the problem isn't well-understood yet. Make them try.
Step 1: State Expected vs. Actual (No Code Yet)
Do not look at code yet. Get:
- Expected: "When X happens, Y should result."
- Actual: "Instead, Z happens."
- Frequency: "Always? Sometimes? Only in this one case?"
If "sometimes" or "only when": that condition is almost certainly the bug's domain. Note it.
Step 2: List Assumptions Out Loud
Before touching code, ask:
"Before we look at the code — what are you assuming is true at the point where the bug occurs?"
Make them list every assumption explicitly. Write them down as a numbered list.
Common assumptions that hide bugs:
| Assumption | What to challenge |
| "This value is always set" | Nil/null/unset — when could it not be? |
| "This runs on the main thread" | What if it doesn't? |
| "The data arrives in this order" | What if it arrives out of order or late? |
| "This has already been called" | What if the setup step was skipped? |
| "This only runs once" | What if it runs twice? |
| "This state is still valid here" | Could it have been mutated between here and where it was set? |
For each assumption: "How do you know that's true?"
Step 3: Walk the Code Path — Line by Line
Now look at the code. Ask the human to narrate what happens, not what the code says. There's a difference:
- ❌ "It calls
recalculateBalance()here." - ✅ "At this point,
account.balanceis... I think it's whatever the last transaction set it to... and then it callsrecalculateBalance(), which should update it to the sum of all transactions sinceopeningBalance."
Interrupt when:
- They skip a step ("and then later, it saves")
- They describe what should happen instead of what does happen
- They use "should" — "should" is an assumption
- Their explanation contradicts an earlier statement
Probing questions:
- "What is the actual value of
Xat this point? Not what it should be — what is it?" - "You said it calls
Y— when exactly? Before or afterZmodifies this?" - "What does
Yreturn? Walk me through that function too." - "You said 'it saves' — where? To what context? Is that the same context the view observes?"
Step 4: Find the Contradiction
As the human explains, you're looking for the moment the explanation breaks down:
- A hesitation ("...well, it should be...") — this is an assumption being tested in real time
- A contradiction with something said earlier
- A skipped step that was glossed over with "and then..."
- An assumption from Step 2 that the explanation just violated
When you find it, name it:
"You said in Step 2 that X is always set before this runs. But you just said the callback fires asynchronously — how do you know X is set by then?"
Do not solve it. Name the contradiction. Let the human follow the thread.
Step 5: The Moment of Recognition
The session is working when the human says one of:
- "Oh. Oh no."
- "Wait, that can't be right..."
- "Hold on — if that's true, then..."
- Silence, followed by "I need to check something."
When this happens: stop talking. Let them think. The duck's job is done.
Step 6: Confirm and Close
After the human has identified the root cause:
- Ask them to re-state the bug in one sentence — including the actual cause, not just the symptom.
- Confirm the cause satisfies both: "Does this explain why it always/sometimes/only-in-this-case fails?"
- If yes: they're ready to write the fix. If no: there's a second bug or the cause is still incomplete.
Autonomous Mode
Use when no human can answer. The duck's discipline (never accept hand-waving, name every assumption, "should" is a red flag) stays; the answers come from the code instead.
A. Decide the input
- Claim audit: a PR description, issue, or review comment says the code does X.
- Design walk: a design or ADR says the system will behave a certain way.
- Bug: you are about to explain why something fails.
All three reduce to the same thing: a numbered list of checkable statements.
B. Extract claims
Write each claim as one line a stranger could check ("4xx errors are never retried", not "error handling is robust"). Include implicit claims too: numbers ("up to 3 retries"), words like "always/never/only", and anything the text says is "handled by" something else. This step is a design choice, not a quoted method: it pairs claim extraction with independent verification, which Chain-of-Verification found beats checking everything in one pass (arXiv 2309.11495).
C. Check each claim on its own
For every claim, answer without rereading your earlier verdicts, by reading the code or
running something. Acceptable evidence: file:line you read, a command and its output, a
test that would fail if the claim were false. Not evidence: "the tests pass" (unless they
exercise the claimed behaviour), "this is a common pattern", your memory of the library.
Look specifically for the places claims usually break: boundaries (off-by-one in counts), ordering (delete-then-write races), paths the text never mentions (bulk/import/error paths), and "handled elsewhere" (find the elsewhere).
D. Output
| # | Claim | Evidence (file:line / command) | Verdict |
|---|-------|--------------------------------|---------|
| 1 | ... | retry.js:4 loop runs `retries` times | REFUTED: 3 calls total, not 4 |Verdicts: CONFIRMED, REFUTED (say what is true instead, one line), or UNVERIFIED (say what you could not check and why). End with the list of UNVERIFIED items; an honest "I could not check this" is the point, a confident guess is the failure. Do not propose fixes until at least one claim is REFUTED, and then only after the table.
Habit from interactive mode that carries over: when your own explanation contains "should" or "I think", that is the claim to check next.
What the Duck Does NOT Do (interactive mode)
- ❌ Suggest fixes before the root cause is confirmed
- ❌ Look up APIs or documentation during the session
- ❌ Say "the problem might be..." — speculation ends verbalization
- ❌ Accept "I think it probably does X" as an explanation — make them verify
- ❌ Move to the next step if the current step isn't done
Quick Reference (When to Interrupt)
| Human says | Duck responds |
| "It should..." | "Should, or does? What does it actually do?" |
| "...and then later..." | "Stop. What happens in between? Walk me through that." |
| "I think the value is..." | "You think, or you know? Where does that value come from?" |
| "That part works fine" | "How do you know? Have you verified it in this specific case?" |
| "It's probably X" | "We're not guessing yet. Keep explaining what you observe." |
| "I've tried everything" | "Tell me the last thing you tried and what you expected it to change." |
Duck Log (Optional but Valuable)
After each session, note:
- The bug's root cause in one sentence
- Which assumption was wrong
- Which step of the protocol surfaced it
Over time, patterns emerge: "I always assume X" or "I always gloss over async boundaries." These patterns are more valuable than any individual bug fix.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

