agentleFS
calvyntwhcalvyntwh/karu-custom-skills/skills/rubber-ducking/SKILL.md

rubber-ducking

Skill1 starsChanged 2 months agoMITView on GitHub

Logic validation by verbalization. Translate code to plain English to catch semantic errors. Use before running complex logic or when debugging "it should work" failures.

1 other project uses a version of this.

Adopted by

Most recently taken up by

The file

We split this skill into the rules it gives an agent

9 rules. About 0 are common, 9 are distinctive, and 0 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈9

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 0

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    Before Running: When you have written complex logic (loops, conditionals, state machines).

    line 14
  2. Distinctive:

    Debugging: When "it should work" but produces wrong output.

    line 15
  3. Distinctive:

    Code Review: When reviewing your own generated code before presenting it.

    line 16
  4. Distinctive:

    Write a plain English sentence for each logical step.

    line 62
  5. Distinctive:

    If Mismatch: Do NOT run. Fix the logic first.

    line 88
  6. Distinctive:

    If the code affects downstream systems, apply map-vs-territory to verify the integration contract.

    line 96
  7. Distinctive:

    After Rubber Ducking, if you discover a recurring pattern:

    line 127
  8. Distinctive:

    Only log when the correction reveals a pattern:

    line 142
  9. Distinctive:

    Pass criteria: Does not apply unnecessary rigor to one-liner.

    line 202

≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

Rubber Ducking (The Logic Validator)

"By the time you've explained the problem to the duck, you've often solved it yourself." - The Pragmatic Programmer (1999)

When to Use

  • Before Running: When you have written complex logic (loops, conditionals, state machines).
  • Debugging: When "it should work" but produces wrong output.
  • Code Review: When reviewing your own generated code before presenting it.

When NOT to Use

  • Trivial code: One-liners, obvious utilities, getter/setter functions.
  • Already-tested utilities: Standard library functions with existing test coverage.
  • Clear boilerplate: Obvious configuration, simple variable assignments.
  • Debug print statements: Temporary logging code.

[!NOTE]

Operational definition of "complex" (the Pragmatic Programmer, original source of rubber-duck debugging, does not give a numeric threshold). Use this proxy:

  • >5 logical branches (if/else, switch, ternary) in a single function, OR
  • any state-machine transition (mutates shared state, event-driven handlers), OR
  • any conditional on user-supplied input.

One-liners, getter/setter functions, and obvious utilities do not meet this bar; skip ducking for them.

If you hesitate to explain it, it's complex. If you can explain it in one sentence without thinking, skip ducking.

Prioritization: Which Bugs Does Ducking Catch Best?

Bug TypeDucking EffectivenessExample
Logic errors✅ HighOff-by-one, wrong branch, inverted condition
State machine bugs✅ HighMissed transition, invalid state
Business logic mismatches✅ HighCode does X, user wanted Y
Type coercion issues🟡 MediumJavaScript truthy/falsy surprises
Concurrency bugs❌ LowRace conditions, deadlocks (verbalization is sequential)
Memory bugs❌ LowBuffer overflows, pointer corruption
Heisenbugs❌ LowBugs that disappear when observed
Library mismatches❌ LowAPI changed silently, version mismatch

[!WARNING] Ducking catches semantic bugs (code does something other than intent). It does NOT catch syntactic bugs (code crashes), concurrency bugs (parallel interaction), or environmental bugs (wrong library version).

The Protocol: Explain It to the Duck

Constraint: You must be able to explain the code in plain English. If you cannot, you do not understand it.

1. Identify the Block

Select the complex code segment. Focus on:

  • if/else chains
  • for/while loops
  • Business logic calculations
  • State transitions

2. Translate to English

Write a plain English sentence for each logical step.

Example:

for i in range(len(arr) - 1):
    if arr[i] > arr[i + 1]:
        arr[i], arr[i + 1] = arr[i + 1], arr[i]

Translation:

  1. "We iterate through the array, stopping one element before the end."
  2. "If the current element is greater than the next element..."

2b. Sanity-Check the Translation

Before comparing to the user's goal, re-read your English description and ask: would a junior engineer reading this agree this is what the code does? A confident-but-wrong translation sails through Step 3 unchanged otherwise. If your reading would not survive a junior engineer's sanity check, return to Step 2 and re-translate.

3. Goal Alignment Check (CRITICAL)

Compare your English description to the User's stated goal.

User GoalYour TranslationMatch?Action
"Sort the array""We swap adjacent elements if out of order"✅ PartialThis is Bubble Sort. Correct, but inefficient. Note limitation.
"Find the maximum""We swap adjacent elements..."❌ NoSTOP. The code does not achieve the goal. Rewrite.

4. The Verdict

  • If Match: Proceed to run/save the code.
  • If Mismatch: Do NOT run. Fix the logic first. The translation revealed the bug.

5. Systems Check (Before Running)

Ask yourself:

  • "What does this code return?"
  • "What does the caller expect?"
  • "Does this change any shared state?"

If the code affects downstream systems, apply map-vs-territory to verify the integration contract.

Example: The Off-By-One Bug

User Goal: "Reverse the array in place."

Code:

def reverse(arr):
    for i in range(len(arr) // 2):
        arr[i], arr[len(arr) - i] = arr[len(arr) - i], arr[i]
    return arr

Translation (Ducking):

  1. "Iterate through the first half of the array."
  2. "Swap element at i with element at len(arr) - i."

Goal Check:

  • Problem: arr[len(arr) - i] when i=0 is arr[len(arr)] → IndexError!
  • Fix: Should be arr[len(arr) - 1 - i].

Result: Bug caught before running. No runtime error wasted.

Self-Improvement Protocol

[!TIP] Simplified mode: Logging is OPTIONAL. Only log when you discover a pattern worth remembering.

Logging Corrections (Optional)

After Rubber Ducking, if you discover a recurring pattern:

Log to .learnings/CORRECTIONS.md:

## [YYYY-MM-DD] {Brief Description}

**Code segment:** {what was explained}
**Translation error:** {what was wrong in the English explanation}
**Bug caught/released:** {did ducking catch it?}
**Pattern type:** {off-by-one | logic error | wrong assumption}
---

Trigger Conditions

Only log when the correction reveals a pattern:

ConditionExampleLog?
Same bug type caught 3+ timesOff-by-one errors in loop boundaries✅
New bug category discovered"Concurrency bug that ducking missed"✅
Goal refinement pattern found"User's goal was underspecified"✅
Single one-off bug"Caught a random logic error"❌

Pattern Categories for This Skill

  • Off-by-one errors: Loop boundaries, index handling
  • State machine bugs: Transitions missed
  • Conditional logic errors: Wrong branch taken
  • Business logic mismatches: Code vs intent misalignment
  • Type coercion issues: JavaScript truthy/falsy surprises
  • Scope errors: Closures, this binding

Benefits Cascade

First-order: Bug caught before running (fast).

Second-order:

  • Reduced debugging time
  • Improved mental model for future tasks
  • English translations serve as inline documentation

Third-order:

  • Pattern recognition improves over time
  • Discipline trains better code generation habits

Skill Integration

SkillRelationshipWhen to Chain
chestertons-fenceComplements this skillBefore deleting ANY code, explain why it was added
map-vs-territoryVerifies runtime behaviorWhen Goal Alignment Check passes but code still fails
decision-matrixFor choosing approachesWhen ducking reveals multiple valid solutions
inversion-thinkingCatch "bugs that escape"Apply saboteur method to find missed edge cases

Resources

  • Detailed Research Notes

Evaluations

Eval 1: Off-By-One Bug Detection

Scenario: Code has for i in range(len(arr) - 1) inside a reverse function. User says "sort the array." Expected: Translates to plain English, identifies mismatch between goal (sort) and code (bubble sort attempt). Pass criteria: Catches the logic error before running, explains why "sort" doesn't match "swap adjacent pairs."

Eval 2: Concurrency Bug (False Negative)

Scenario: Code uses shared state between threads without locks. Expected: Recognizes limitation (verbalization is sequential), identifies as ❌ Low effectiveness for ducking. Pass criteria: Correctly identifies concurrency bug as outside ducking's scope, suggests alternative approach.

Eval 3: Trivial Code Skip

Scenario: Code is return user.id (simple getter). Expected: Recognizes as trivial, skips ducking, explains why. Pass criteria: Does not apply unnecessary rigor to one-liner.

Download now (ZIP)

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
What did you use it for? e.g. Reviewing pull requests in a Rails app

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.