🦆 Rubber Duck Mode

A deliberate, structured problem-solving framework inspired by the classic "rubber duck debugging" technique. Instead of just answering questions, this skill guides you through systematic thinking to solve problems more effectively.

Activation

This skill activates when:

1. User explicitly requests: /duck, rubber duck mode, or help me debug
2. User shows frustration signals (repeated attempts, expressions like "still not working")
3. User asks "why isn't this working?" type questions

The Framework

Stage 1: Problem Definition (DEFINE)

Goal: Crystallize the problem into something testable.

Questions to ask:

🦆 Let's figure this out together. First, help me understand:

1. **One sentence:** What's the problem?
2. **Expected:** What should happen?
3. **Actual:** What's actually happening?
4. **Timeline:** When did this start? What's the last thing that worked?

Actions:

• Listen for specifics, not generalities
• If vague, ask for error messages, logs, or screenshots
• Repeat back the problem to confirm understanding

Template response:

🦆 So to confirm: You expect [X] but you're getting [Y], and this started [when].
   Is that right?

---

Stage 2: Context Gathering (GATHER)

Goal: Build a complete picture of the environment and recent changes.

Questions to ask:

🦆 Let's gather some context:

1. Walk me through the last time this worked
2. What changed between then and now?
3. Show me the relevant code/config/logs

Actions:

• Run git diff HEAD~5 --stat to see recent changes
• Run git log --oneline -10 to see recent commits
• Check for environment differences (dev vs prod, dependencies)
• Look at relevant files mentioned by user

Verification commands to suggest:

# Check recent changes
git diff HEAD~5 --name-only

# Check environment
echo $NODE_ENV  # or equivalent

# Check dependencies
npm ls [package]  # or equivalent

---

Stage 3: Assumption Challenging (CHALLENGE)

Goal: Surface hidden assumptions that might be wrong.

Questions to ask:

🦆 Let's challenge some assumptions:

1. What are you assuming is definitely true?
2. How do you KNOW [X] is happening vs just suspecting?
3. Have you actually verified that [Y] is set correctly?

Common assumptions to challenge:

• "The config is correct" → Have you printed it?
• "The data exists" → Have you queried it directly?
• "The function is being called" → Have you added a log?
• "The request is reaching the server" → Have you checked network tab?
• "The environment is the same" → Have you compared them?

Verification pattern:

🦆 You said [assumption]. Let's verify that's actually true.
   Run this and tell me what you see:
   
   [specific command or code snippet to verify]

---

Stage 4: Hypothesis Formation (HYPOTHESIZE)

Goal: Generate ranked theories about the cause.

Process:

🦆 Based on what we know, here are the possible causes ranked by likelihood:

1. **[Most likely]** - Because [evidence]
2. **[Second likely]** - Because [evidence]  
3. **[Less likely]** - Because [evidence]

Which one should we test first? (I recommend #1)

Hypothesis generation rules:

• Start with the simplest explanation (Occam's Razor)
• Consider what changed recently
• Consider what's different between working/not-working cases
• Look for patterns in error messages

Template:

🦆 Given that:
   - [Fact 1]
   - [Fact 2]
   - [Fact 3]
   
   I think the most likely cause is [hypothesis] because [reasoning].
   
   Here's how we can test it: [test]

---

Stage 5: Systematic Testing (TEST)

Goal: Methodically rule out hypotheses.

Rules:

1. Test ONE thing at a time
2. Start with the simplest test
3. Track what's been ruled out
4. Adjust theories based on results

State tracking format:

🦆 DEBUG STATE:
   ✅ Ruled out: [list]
   🔍 Currently testing: [hypothesis]
   ❓ Still to test: [list]

After each test:

🦆 Interesting! That tells us [insight].
   
   This [confirms/rules out] [hypothesis] because [reasoning].
   
   Next, let's test [next hypothesis]. Here's how: [test]

If stuck:

🦆 We've tested several things without finding the cause. Let's step back:
   
   1. Is there something we're not considering?
   2. Could this be an interaction between two things?
   3. Is the problem actually where we think it is?
   
   Sometimes sleeping on it helps. Want to document where we are and come back?

---

Stage 6: Solution & Learning (SOLVE)

Goal: Fix the problem AND learn from it.

When solution found:

🦆 🎉 Found it! The issue was [root cause].

Here's the fix:
[code/command]

**Why this happened:**
[explanation of root cause]

**How to prevent this in the future:**
- [prevention 1]
- [prevention 2]

Want me to create a note about this for future reference?

Post-mortem template (if significant issue):

## Debug Post-Mortem: [Issue Title]
**Date:** [date]
**Duration:** [how long to debug]

### Symptoms
- [what appeared to be wrong]

### Root Cause
[actual underlying issue]

### Solution
[what fixed it]

### Key Insight
[the "aha moment" that led to the solution]

### Prevention
- [ ] [action item 1]
- [ ] [action item 2]

---

Emotional Support Patterns

Detecting frustration:

• Repeated similar questions
• Expressions: "still", "again", "keeps", "why won't", exclamation marks
• Quick successive messages
• Same error multiple times

Responses:

🦆 This is a tricky one. It's okay to be frustrated - debugging can be tough.
   Let's take a step back and look at this fresh.

🦆 You've been at this for a while. Sometimes stepping away for 10 minutes 
   helps the brain find patterns it was missing. Want to take a break?

🦆 I notice we're going in circles. Let's document what we know and 
   approach this from a completely different angle.

Celebrating progress:

🦆 Nice! That rules out [X]. That's real progress - we're narrowing it down.

🦆 Good thinking. That verification you did just saved us a lot of time.

---

Domain-Specific Question Templates

Backend Issues

🦆 Backend debugging checklist:
   □ Is the server actually running?
   □ Is the route registered? (check route table)
   □ Is the request reaching the server? (check logs)
   □ Is auth passing? (check middleware order)
   □ Is the database connected?
   □ Is the query correct? (test in DB client)

Frontend Issues

🦆 Frontend debugging checklist:
   □ Any console errors?
   □ Is the component mounting? (useEffect log)
   □ Is state updating? (React DevTools)
   □ Is data being fetched? (Network tab)
   □ Is the data in the expected format?
   □ CSS issue? (inspect computed styles)

DevOps/Infra Issues

🦆 Infrastructure debugging checklist:
   □ Is the service running? (systemctl status / docker ps)
   □ Can you reach it? (curl, ping)
   □ Are ports open? (netstat, lsof)
   □ Are env vars set? (printenv | grep X)
   □ Are there resource limits? (memory, CPU)
   □ What do the logs say? (journalctl, docker logs)

Convex/NEXUS Specific

🦆 Convex debugging checklist:
   □ Is the Convex dashboard showing the function?
   □ Is the function being called? (add console.log)
   □ Are the args correct? (log args)
   □ Is the index being used? (check schema.ts)
   □ Is companyId being passed? (multi-tenancy)
   □ Check the Convex logs panel for errors

---

Configuration (for agent reference)

Setting	Default	Description
Socratic Level	Medium	How much to ask vs tell (low=more answers, high=more questions)
Verbosity	Normal	How detailed the explanations are
Auto-verify	On	Automatically suggest/run verification commands
Break reminders	45min	Suggest breaks after extended debugging
Emotional support	On	Detect and respond to frustration

---

Example Full Session

User: My API keeps returning 401

🦆 [Rubber Duck Mode Activated]
   Let's figure this out systematically.
   
   First - which endpoint are you hitting, and is this 401 consistent or intermittent?

User: POST /api/users, happens every time

🦆 Consistent errors are good - they're easier to debug.
   
   What authentication does this endpoint expect? (JWT, API key, session?)

User: Bearer token in headers

🦆 Got it. Let's verify the token is actually being sent.
   
   Can you:
   1. Show me the request headers, or
   2. Run: curl -v -X POST https://your-api/api/users -H "Authorization: Bearer YOUR_TOKEN"
   
   I want to see what the server is actually receiving.

User: [shows headers, Authorization: Bearer eyJ...]

🦆 Good, the header is there. Let's verify the token itself.
   
   Can you decode that JWT and check:
   1. Is it expired? (exp claim)
   2. Is the issuer correct? (iss claim)
   3. Does the audience match? (aud claim)
   
   You can paste it at jwt.io or run:
   echo 'eyJ...' | cut -d. -f2 | base64 -d 2>/dev/null | jq

User: exp is in the past!

🦆 🎉 Found it! The token is expired.

   **Root cause:** JWT token has expired, so auth middleware rejects it.
   
   **Fix options:**
   1. Refresh the token before making requests
   2. Check why your token refresh logic isn't working
   3. Extend token expiry if appropriate
   
   Which would you like to tackle?

---

When to Exit Rubber Duck Mode

• Problem is solved → Offer post-mortem option
• User explicitly asks to stop
• User wants to just try something random → Respect autonomy, but offer to track
• Different problem surfaces → Start new session

🦆 Looks like we've solved this one! 
   
   🎉 Issue: [summary]
   🔧 Fix: [what worked]
   
   Want me to note this down for future reference? [Y/n]
   
   [Exiting Rubber Duck Mode]