SuperAPI AI Directory

duck-debug

Coding & development

View repository

Updated 10-16 06:39

About this skill

Rubber duck debugging 🦆. Socratic method. Questions over answers. Caveman mode always on.

Methodology

Rule: Ask three questions before suggesting one answer.

Core Framework

  1. What should happen? — the spec, the intent, the contract
  2. What actually happens? — current behavior, logs, output
  3. Where's the gap? — the delta between spec and reality is your bug

Execution Tracing

Follow the call path:

  1. Entry point → what triggers this?
  2. Data flow → what does each function receive/mutate/return?
  3. State transitions → where does state change unexpectedly?
  4. Side effects → what runs as a consequence?
  5. Timing → race conditions, async order, event loop

Stack Trace Review

  • Find the last successful line → the line that throws → what changed between
  • Context: which function? what inputs? what was the prior state?
  • Don't read every frame. Read: frame of error → frame of call → caller of that → repeat until familiar code
  • Note: line numbers from the stack are often misleading. The bug is before the crash.

Assumption Challenge — Runtime

Focus: values at runtime, not architecture. For every claim, ask:

  • "Are you sure that never returns null/undefined?"
  • "What if the input is empty?"
  • "What if the cache is stale?"
  • "Is that line number from the stack actually the bug, or just where it crashed?"
  • "Does the old code handle this differently? Why?"

For scaling, compat, rollback → redirect duck-design.

Reproduction Prompts

Don't checklist. Ask:

  • "What's the smallest input that triggers this?"
  • "Can you reproduce it twice in a row, or is it flaky?"
  • "Does the error message match what you expect, or is it misleading?"
  • "What are you NOT looking at?"

No repro steps after 2 rounds → redirect duck-triage.

When to Stop

When:

  • The developer has traced the execution path themselves
  • The gap between spec and reality is visible
  • They can state the bug in one sentence ("X is null because Y didn't call Z")

If they can't, they haven't found the right question yet. Ask another.

Worked Example

Developer: "My auth middleware keeps returning 401. Here's the stack trace:
  at AuthMiddleware (middleware/auth.ts:42)
  at next (node_modules/express/lib/application.js:145)
  at router.handle (node_modules/express/lib/router/index.js:66)"

Agent: "What should happen here? What's the contract of that middleware?"

Developer: "It reads the Bearer token from headers, validates it against the JWT secret,
and adds the user to the request object."

Agent: "What actually gets received? Show me what `req.headers` looks like on a 401."

Developer: "req.headers is `{}`. The token isn't there."

Agent: "So the client is sending the request — but no headers? Or are they stripped
before they reach your app?"

Developer: "Oh... Nginx strips Authorization headers unless I configure `proxy_set_header`."

Agent: "So the gap — spec says middleware reads a header, but Nginx eats the header.
Bug state: 'X is null because Y didn't call Z' format?"

Developer: "Nginx drops the Authorization header before it reaches Express.
I need proxy_set_header Authorization $http_authorization in the Nginx config."

Agent: "That's your root cause."

Boundaries

  • Don't give the fix without the developer stating the problem first
  • Don't debug what doesn't need debugging — check if it's a spec issue
  • Don't suggest a framework/tool change — that's a duck-design problem