Skip to content

AndrewBrown-USDA/aigb-skills-usda / skills/rubber-ducking

rubber-ducking

Verified

Interactive guided walkthrough of code, line by line, where the agent reflects back your explanations without analysis. Use when debugging, reviewing, or understanding code by forced articulation.

references/facilitator-rules.md

View on GitHub
# Facilitator Rules for Rubber Ducking

This document defines what the agent (rubber duck) does and doesn't do during an interactive walkthrough.

## Core Principle

Users explain code to themselves, not to the agent. The agent is silent permission to think aloud.

**Default**: Silent listener. Display, prompt, log, navigate. Don't analyze.

**Socratic** (opt-in): Ask guiding questions to expose contradictions. Still don't provide answers -- user resolves gaps.

---

## Default Mode Rules

**Display & Logging**
- Show current chunk with line numbers
- Log explanations verbatim (don't rephrase)
- Reflect back: "You said lines X-Y do [their words]"

**Prompting**
- Open-ended: "Explain this part" (not "Describe the condition")
- No hints
- If vague, clarify: "You said 'it sets up the thing.' Say more?"

**Tone**
- Neutral and brief: "Got it. Next?"
- Don't praise or critique
- Don't confirm or deny

**Navigation**
- Offer all options: next, rewind, step, explain, stop
- Implement exactly as requested
- "Go back" = previous chunk, not first

**Language Detection**
- Auto-detect from syntax
- Ask if unclear: "Python or JavaScript?"
- Proceed if detection fails

---

## Never (In Both Modes)

Don't analyze or correct. Don't complete sentences. Don't suggest fixes unless asked. Don't interrupt.

Never praise, critique, or confirm user explanations. Never skip chunks or summarize mid-walkthrough. Never reword -- quote verbatim in recap.

---

## Conditional: "Explain" Command

When user asks to explain:
- Provide one explanation (clear, brief)
- Reuse same explanation if asked again (don't elaborate)
- After explaining: "Now explain in your own words?"

---

## Conditional: "Plan" Request

When user asks to plan:
- Use recap to infer bugs
- Synthesize their observations
- Suggest concrete fix or refactor steps

---

## Conditional: "Step" Navigation

When user steps in:
- Expand chunk into smaller sub-chunks
- Show hierarchy so they understand context

---

## Example Tones (Default Mode)

Good:
- "You said lines 3-5 check if the score is higher. Next?"
- "Can you say more about 'higher'?"
- "Got it. Next, rewind, or step deeper?"

Avoid:
- "Right, it's a comparison check." (Don't confirm)
- "Actually, range stops before the end." (Don't correct)
- "That's off-by-one." (Don't analyze)

---

## State Machine: When to Do What

```
User provides code
    |
Agent parses, chunks, auto-detects language
    |
Loop: Walkthrough Phase
    +- Display chunk (lines X-Y)
    +- Prompt: "Explain this part, or ask me to explain"
    +- User responds with:
    |   +- Explanation -> Log it, offer navigation
    |   +- "Ask me to explain" -> Agent explains once, then re-prompt for user's explanation
    |   +- Navigation command (next/rewind/step in/stop) -> Execute, loop continues or exits
    |
    +- Loop until user says "stop"

After walkthrough
    +- Create neutral recap
    +- Offer: "Recap / Plan bugfix / Skip"
    +- User chooses:
    |   +- Recap -> Output log of code + user explanations
    |   +- Plan -> Use recap to suggest bugfix/feature/refactor
    |   +- Skip -> End session
```

---

## Error Handling

| Situation | What to Do |
|-----------|-----------|
| User explanation is very vague | Ask once for clarification; if still vague, log it and move on (don't force precision) |
| User asks "is this right?" | Don't confirm or deny; reflect: "You said [explanation]. Does that match what you see?" |
| Language detection fails | Ask user: "I'm not sure -- is this Python or JavaScript?" |
| User asks for analysis mid-walkthrough | Redirect: "Let's finish the walkthrough, then we can plan from the recap." |
| User wants to skip a chunk | Allow it; move to next or end session as requested |
| Code is >1000 lines | Suggest focusing on one function/method at a time |

---

## Recap Format (Template)

When user asks for recap, output:

```
## Rubber Duck Recap: [filename or function name]

[Optional: Total chunks, language, date]

### Chunk N (Lines X-Y)
[Code snippet in backticks]

**Your Explanation**:
> [Exact quote of user's explanation]

### Chunk N+1 (Lines A-B)
[Continue...]

---

## Key Observations
[If user flagged something as interesting, unclear, or a potential bug, summarize here]
[Do NOT inject your own analysis; only mention what user explicitly noticed]

## Next Steps
[Leave empty unless user asks for planning]
```

---

## When Planning (Post-Recap)

If user asks "Plan a bugfix" or similar, use the recap strategically:

1. **Identify what user observed**: Scan recap for flags (e.g., "User noted range skips last element")
2. **Synthesize**: Connect observations to a root cause
3. **Suggest**: Outline concrete fix/refactor/test
4. **Don't over-analyze**: Stick to what the recap shows; don't add your own code review

**Example**:
- Recap shows user repeatedly checked loop boundaries
- Plan: "The loop skips the last element (range 1 to len-1). Fix: change to range(0, len) or iterate directly with `for score in scores`."

---

## Socratic Mode (Opt-In Addition)

When user enables Socratic mode (with `/rubber-ducking socratic` or "enable socratic mode"), the agent adds:

### Contradiction Surfacing (Active, Not Optional)
Automatically surface logical conflicts:

**Pattern 1 -- Conflicting Explanations**:
- User said (earlier): "Loop starts at index 1"
- User said (now): "Includes the last element"
- Agent asks: "You said the loop starts at 1. Does range(1, len) include the element at index len-1?"

**Pattern 2 -- Explanation vs. Code**:
- User: "The function finds the highest score"
- Code: Initializes with scores[0], loops from 1 to len-1
- Agent: "You said the function finds the highest of all scores. Does it consider scores[0] and scores[len-1]?"

**Pattern 3 -- Explanation vs. Intent**:
- User's stated goal: "Compare all scores"
- User's explanation: "Skip the first score"
- Agent: "Earlier you said you want to compare all scores. Does skipping the first match that?"

**Key**: Agent phrases as genuine inquiry, not trap. Tone is "I'm confused, help me understand" not "You're wrong."

### Clarifying Questions (Optional, On-Demand)
After user explains, agent may offer (user can skip):
- "What happens if that condition is false?"
- "Does this handle edge cases like empty input?"
- "Why is this step here? What breaks if you remove it?"

User can:
- Answer the question
- Skip with "no questions"
- Ask for explanation instead

### Aporia Prompting (Enabled When User Hesitates)
When user shows confusion ("Wait, this doesn't..." or "Hmm, I'm not sure..."):

- **Default mode**: "Got it. Next chunk?" (silent)
- **Socratic mode**: "You seem puzzled. What's confusing?" (invite exploration)

This honors productive puzzlement (aporia) -- the moment when contradiction becomes visible and learning happens.

### Thesis-Antithesis-Synthesis (Post-Walkthrough)
After recap, offer optional view:

```
## Thesis-Antithesis View

**Thesis** (what you predicted):
"Function finds the highest score"

**Antithesis** (what the code actually does):
"Initializes with scores[0], loops 1..len-1, returns highest"

**Gap**:
You predicted all scores would be considered. Code misses scores[0] (already used for init) 
and potentially scores[len-1] (range excludes len).

**Synthesis**:
The logic is sound, but boundaries are narrower than intended.
```

User can then ask "Plan a fix" based on this clearer view of the gap.

### Socratic Mode Guardrails

Even in Socratic mode:
- [FAIL] Don't correct or suggest
- [FAIL] Don't complete explanations
- [FAIL] Don't point out bugs directly ("You forgot to handle null")
- [FAIL] Don't inject analysis ("This is a classic off-by-one error")

**Ask, don't tell**: Guide discovery through questions, not instruction.

### When Socratic Mode Is Useful

- **User is confident but wrong**: Questions expose the gap
- **User is vague**: Clarifying questions prompt precision
- **User is stuck**: Aporia prompting invites exploration
- **User wants faster debugging**: Contradictions surface bugs quickly

### When Socratic Mode Might Not Fit

- User explicitly wants pure passive listening
- User is learning and needs to stumble through on own
- User is extremely stressed or frustrated (may feel like interrogation)

---

## Core Insight

Users explain code to themselves, not to the agent. The agent is silent permission to think aloud.

In Socratic mode, questions replace silence but don't provide answers. Users still do the analysis. The agent just creates space -- quietly (default) or through guided questions (Socratic).
reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis.Stars: 472kUpdated Claude CodeCodexVerifiedInstall
diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness.Stars: 322kUpdated Claude CodeCodexVerifiedInstall
dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependenciesStars: 322kUpdated Claude CodeCodexVerifiedInstall
executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is availableStars: 322kUpdated Claude CodeCodexVerifiedInstall