rubberDucky

🦆 DebugDuck --- Learn Debugging, Not Copy-Pasting

An AI-powered VS Code extension that teaches you how to debug using progressive hints, pattern recognition, and real learning feedback.

💡 Inspiration

We've all been there. It's 3 AM, your code is broken, and ChatGPT becomes your best friend. You copy the fix, paste it in, and... it works! Magic!

But here's the problem: you learned absolutely nothing.

The next day, you hit the same bug. Back to ChatGPT. Copy. Paste. Repeat. You're stuck in an infinite loop:

while (bug exists) {
  askChatGPT();
  copyPaste();
  understanding = 0;
}

We realized we were building a dependency on AI, not improving with AI. We weren't becoming better developers—we were becoming better copy-pasters.

That's when we asked: What if AI refused to give you the answer?

What if your debugging assistant was more like a patient teacher than a know-it-all? What if it tracked YOUR specific mistakes and actually prevented you from making them again?

What if... your debugging assistant was a duck? 🦆

🎯 What It Does

DebugDuck is a VS Code extension that teaches you to debug through three core principles:

1️⃣ Progressive Hints (Socratic Method)

Instead of giving you the solution, DebugDuck guides you to discover it yourself through 4 levels of hints:

Level 1: A thought-provoking question
Level 2: Points to the general problem area
Level 3: Explains the missing concept
Level 4: Shows a similar example (but still not YOUR exact solution)

Example:

// Your buggy code
const user = users[id].name;

🦆 Hint 1: "What happens if 'id' doesn't exist in the array?"
   [You think...]

🦆 Hint 2: "users[id] might be undefined. What happens when you 
            access .name on undefined?"
   [You try something...]

🦆 Hint 3: "You need to check if users[id] exists before accessing 
            its properties. This is called optional chaining."
   [Lightbulb moment!]

🦆 Hint 4: "Here's how you might safely access it:
            const name = users[id]?.name || 'Unknown';"

✅ You fixed it! You needed 3 hints.
📊 Last time you hit this bug type: 4 hints. You're improving! 📈

The system measures your learning progress by tracking how many hints you need over time. If you're improving, the average goes down:

$$ \text{Learning Rate} = \frac{\sum_{i=1}^{n} \text{hints}_i}{n} \quad \text{(lower is better)} $$

2️⃣ Pattern Recognition & Prevention (Under Construction 🚧)

DebugDuck doesn't just help you fix bugs --- it learns YOUR specific patterns.

Once fully implemented, if it detects that you are about to repeat a mistake you've made multiple times before, it will warn you in real time:

// You start typing...
const user = users[userId].

🦆 ⚠️ WAIT! You've made this mistake 5 times before.
Did you check if users[userId] exists?

💡 Suggestion: Use optional chaining (?)

The goal is prevention, not correction.

3️⃣ Learning Dashboard

Your progress is visualized with:

Solve Rate: (bugs solved / total bugs) * 100%
Improvement Trends: Week-over-week hint reduction
Pattern Breakdown: Which bug types you're mastering vs. struggling with
Streak Tracking: Consecutive days of active learning

🔨 How We Built It

Tech Stack

Language: TypeScript (type safety + developer experience)
Platform: VS Code Extension API
AI: Claude API (Anthropic) for hint generation
Storage: Local JSON files (privacy-first, no server required)
Runtime: Node.js

Fun fact: We initially built everything using Bun because it's insanely fast --- then realized at the very end of the hackathon that VS Code extensions strictly require Node.js. Cue a last-minute migration panic. ☕😅

Architecture

┌─────────────────────────────────────────┐
│         VS Code Extension               │
├─────────────────────────────────────────┤
│                                         │
│  ┌──────────┐      ┌──────────────┐   │
│  │   UI     │◄────►│   Learning   │   │
│  │ Layer    │      │   Engine     │   │
│  └──────────┘      └──────────────┘   │
│       ▲                    ▲           │
│       │                    │           │
│       ▼                    ▼           │
│  ┌──────────┐      ┌──────────────┐   │
│  │ Webview  │      │   Pattern    │   │
│  │ Panels   │      │   Tracker    │   │
│  └──────────┘      └──────────────┘   │
│                           ▲            │
│                           │            │
│                    ┌──────▼────────┐   │
│                    │  Claude API   │   │
│                    └───────────────┘   │
└─────────────────────────────────────────┘

Core Components

1. Progressive Hint System (learningEngine/hintSystem.ts)

Uses Claude AI with a carefully crafted system prompt that enforces the Socratic method:

const systemPrompt = `You are a patient coding teacher.

CRITICAL RULES:
1. NEVER give the solution directly
2. Guide through questions and hints
3. Each hint progressively more specific
4. Let the student connect the final dots

Generate exactly 4 hint levels:
- Level 1: Thought-provoking question
- Level 2: Point to problem area
- Level 3: Explain missing concept
- Level 4: Similar example (not exact solution)
`;

2. Pattern Tracker (learningEngine/patternTracker.ts)

Implements a custom learning algorithm that:

Categorizes bugs into types (undefined-access, null-reference, async-await, etc.)
Calculates moving averages for hints needed
Detects improvement trends using statistical analysis
Identifies user's strengths and weaknesses

The improvement detection uses a sliding window approach:

Trend_b:

improving if h_b_recent < h_b_historical - ε
stable if |h_b_recent - h_b_historical| ≤ ε
declining otherwise

Where ε = 0.5 is the threshold for meaningful change.

3. Prevention Engine (learningEngine/preventionEngine.ts)

Uses both pattern matching and AI analysis:

Pattern matching: Regex-based detection for common bugs
AI analysis: Debounced Claude API calls for complex code
Confidence scoring: Only shows warnings above 70% confidence

The confidence score combines:

$$ C = 0.4 \cdot P_{\text{pattern}} + 0.6 \cdot P_{\text{AI}} $$

Where $P_{\text{pattern}}$ is 1.0 if regex matches, 0 otherwise, and $P_{\text{AI}}$ comes from the AI model.

4. Storage System (storage/localDB.ts)

Originally powered by Bun's fast file I/O, later migrated back to Node's native fs. Still provides zero server dependency and complete local privacy.

User profiles stored in .debugduck/profile.json
Session history in .debugduck/sessions/YYYY-MM-DD.json
Zero server dependency = complete privacy

🚧 Challenges We Ran Into

1. The "Too Helpful" Problem

Our first version gave hints that were TOO good. Users would get the answer from hint 1 or 2, defeating the purpose.

Solution: We added strict validation to the AI prompt, requiring each hint level to follow specific constraints. We also added a "hint effectiveness score" that measures if hints are actually teaching (users should need 2-3 hints on average, not 1 or 4).

2. The Storage Rollercoaster

We experimented with multiple approaches:

VS Code workspace state (too slow for scale)
Bun SQL (massive overkill)
Bun file I/O (fast but incompatible with VS Code runtime)
Final solution: Node file I/O with optimized batching

Migrating away from Bun late in development was our biggest technical hurdle.

3. Measuring "Learning"

How do you quantify if someone is actually learning? Just tracking "hints needed" isn't enough.

Solution: Multi-factor learning score:

Average hints needed (trending down = good)
Time to solve (faster = good, but weighted less than hints)
Pattern recurrence (same bug repeating = bad)
Solve rate without giving up (higher = good)

Combined score:

$$ L = 0.4 \cdot (1 - \bar{h}/h_{\text{max}}) + 0.2 \cdot (1 - \bar{t}/t_{\text{max}}) + 0.2 \cdot (1 - r) + 0.2 \cdot s $$

Where:

h̄ = average hints needed
t̄ = average time spent
r = recurrence rate
s = solve rate

🎓 Accomplishments That We're Proud Of

1. We Actually Resisted Feature Creep

We wanted to add: team leaderboards, AI code generation, integration with GitHub, automated PR reviews, Slack notifications...

But we didn't. We stayed focused on ONE thing: teaching developers to debug. And we did it well.

2. The Learning Actually Works

We tested it on ourselves throughout development. The pattern tracking GENUINELY caught us making repeat mistakes. The progressive hints ACTUALLY made us think instead of just copying solutions.

3. The UI Doesn't Suck

Let's be honest—most hackathon projects have terrible UI. We used VS Code's webview API to create a dashboard that's actually pleasant to look at. Gradients! Charts! Animations! 🎨

📚 What We Learned

Technical Learnings

AI prompt engineering is an art. Getting Claude to generate "good" hints (not too easy, not too hard) took 50+ iterations of the system prompt.
Local-first is underrated. No server = no auth, no scaling issues, complete privacy, works offline. Why doesn't everything work this way?
VS Code extensions are powerful. We're barely scratching the surface—there's so much you can do with inline decorations, diagnostics, and webviews.

Product Learnings

Teaching is harder than telling. It's WAY easier to just give someone the answer. Making AI that teaches well is genuinely challenging.
Users resist learning. In testing, some people just wanted the answer NOW. Teaching requires buy-in from the user.
Gamification helps. The dashboard, streak tracking, and improvement metrics make learning feel like progress, not punishment.
The best tools are invisible. Real-time warnings that prevent bugs BEFORE you make them? That's the dream. Prevention > cure.

Team Learnings

Work split is crucial. Having one person on backend/AI and one on frontend/UI meant we could parallelize work. Integration points at hours 10, 14, 18 kept us synchronized.
Shared types are non-negotiable. TypeScript interfaces in types.ts saved us from so many integration bugs.
Demo early, demo often. We demoed to friends every 4 hours. Feedback was brutal but necessary.

🚀 What's Next for DebugDuck

🛠️ Complete real-time prevention engine
🌍 Multi-language support (Python, Java, C++)
🦆 Physical IoT rubber duck that quacks when you repeat a mistake

🦆 Why "DebugDuck"?

The name comes from rubber duck debugging—a real technique where programmers explain their code to a rubber duck to find bugs.

But our duck talks back. And teaches. And tracks your patterns. And refuses to give you the answer.

It's like rubber duck debugging met Duolingo had a baby, and that baby really cares about your education. 🦆

💭 Final Thoughts

We didn't build DebugDuck to win a hackathon. We built it because we were frustrated with ourselves.

We were tired of copy-pasting. Tired of not understanding our own code. Tired of making the same mistakes over and over.

We wanted to get better, not just faster.

And if we're being honest? It worked. Using DebugDuck during development actually made us better developers. We started recognizing patterns. Asking better questions. Understanding our bugs.

That's the magic: When your debugging tool makes you better at debugging, you eventually need the tool less.

Which is kind of poetic for an AI tool, when you think about it.

Broken, your code is... Teach you why, the Duck will! 🦆
Made with ❤️ and way too much coffee at Hack&Roll 2026