Socratic Duck：只提問、不給答案的 AI 除錯助手

This is a submission for the Hacktoberfest Open-Source AI Challenge Week 4: Ghost in the Machine

What I Built

You know the rubber duck trick. You explain your bug out loud to a toy on your desk, and somewhere in the middle of the sentence you hear yourself and the problem just falls out. The duck never says a word. That's the whole trick.

AI tools quietly broke that. Now I paste the error, get a fix, and move on without learning why it broke. I did this for months before I noticed I was getting faster and not any better.

So I built the opposite. Socratic Duck reads your code or a screenshot of your error and asks you questions. Only questions. There's a four step hint ladder, and it starts at "what did you expect to happen?" and slowly gets pointier,It never reaches the fix.

Beg for the answer and the patience meter drops. The duck gets grumpier. When my guard catches a reply that was about to give the game away, a rubber stamp slams down on screen: DUCK ALMOST BLABBED. When you finally work it out yourself, you hit Solved it and get a little case file with the root cause in plain words and one flashcard.

Séance Mode is where the theme comes in. Flip the switch and the duck turns into the ghost of a dead language. COBOL, Fortran, Pascal, BASIC or ALGOL, your pick. The scene goes dark, the patience meter becomes a candle, the stamp becomes a wax seal. The spirit haunts your code and refuses to tell you what's wrong, same as the duck. Only the voice changes, the rules don't. Solve the bug and the case file turns into an ofrenda card, because a bug you actually understand gets laid to rest.

Demo

https://socratic-duck.vercel.app/

Code

pythonperfec / socratic-duck

Most AI tools write your code for you. Socratic Duck does the opposite: it reads your bug (text or screenshot), asks questions until you find the cause yourself, and a guard harness blocks any reply that leaks the fix.

🦆 Socratic Duck

A rubber duck debugging companion engineered to interrogate developers about their bugs using Socratic dialogue, strictly built to never give the fix.
Powered by Gemma 4 with an active two-stage guard harness that intercepts and neutralizes answer leaks before they reach the user.
Wrapped in a tactile bathroom aesthetic—floating soap-bubble chat, an animated tiled bathtub, dynamic patience meter, and a slamming rubber stamp.

🏛️ System Architecture

flowchart TD
    subgraph Client ["Frontend: web/ (Vite + React)"]
        UI["Bathroom Workspace (styles.css)"]
        Tub["Bathtub with Animated Water & SVG Duck (4 Moods)"]
        Chat["Soap-Bubble Dialogue Thread"]
        Meter["Yellow Water-Level Patience Gauge (0-100)"]
        Stamp["Rubber Stamp: DUCK ALMOST BLABBED"]
        Case["Case File Post-Mortem & PDF Print Modal"]
    end
    subgraph Server ["Backend: server/ (Node.js Express ESM)"]
        API["POST /api/chat & POST /api/report"]
        subgraph ExecutionFlow ["Response Generation & Guard Flow"]
            ModelGen["1. Model Inference (generateFn)<br/>Google AI Studio Gemma 4"]
            Rule["2. Stage 1: Rule-Based Heuristic Regex<br/>Code fences, spans >20ch, forbidden phrases"]
            Judge["3.

…

How It Works

Every reply goes through the same path: the model writes it, a rule check looks at it, a second model call judges it, and if either one says it leaks, the reply gets thrown away and regenerated. Two retries, then the duck falls back to a canned line asking something safe.
The rule check is dumb on purpose. It catches code fences, phrases like "change this to that", "the fix is", things like that. The judge is another Gemma call that reads the reply and answers one question: did this reveal the fix?
I needed both after something I only found by playing with it. The duck was in its squint mood, and it gave the answer away. No code, nothing the rule check could catch. It just explained the problem in a friendly sentence. Prose leaks are the hard ones, and that's the reason the judge exists.
The benchmark taught me a lesson too. My first version reported 0% leaks with the guard off and 0% with it on. It looked great and it meant nothing, because I was grading replies with the guard's own detector. Of course it agreed with itself. I rebuilt it with a separate grader that gets the real fix for each bug, and three modes: a plain coding assistant, the duck prompt alone, and the duck with the guard. In the quick run the plain assistant leaked on 15 out of 15. The duck prompt alone and the full guard both held at 0 out of 15.

Why Does Open Innovation Matter?

Two backends. gemma-4-26b-a4b-it through Google AI Studio, and a small gemma:2b through Ollama for running offline. I want to be straight about this: the 26B one is a hosted call. The weights are open, but I'm not running them. The offline path is the small model, and it is noticeably weaker.

The guard doesn't care which model sits underneath it. Change one line in the env file and the same checks run on a different model. The Socratic rules and hint ladder live in a plain prompt file and a SKILL.md, so anyone can fork the behavior and make a stricter duck or a gentler one.

And it costs nothing to run locally, which let me hammer the benchmark hundreds of times without thinking about a bill.

A hosted assistant is tuned to be as helpful as possible, and here, being helpful is the exact bug. Running my own model behind a guard I can read made it easier to see where it fails and fix that spot.

The Spirit of It

The ghost in the machine, to me, is the bug that's been sitting in your code the whole time. It already knows what's wrong. The duck is the ghost that knows too, and the only thing it will do is ask you the right question until you see it.

Prize Categories

Best Use of Gemma. Gemma 4 does all of the talking: it reads screenshots and code, asks the questions, judges its own replies for leaks, and writes the case file at the end