interactive-debugging

Interactive Debugging

Use this skill to run a debug loop: hypothesize, instrument, reproduce, inspect runtime logs, fix, verify, and clean up.

Required Paths

• Debug server: .debug/debug_server.*
• Debug log: .debug/debug.log
• Default endpoint: http://localhost:3333/debug

The bundled servers in this skill's scripts/ directory (next to this SKILL.md, not in the project being debugged) are intentionally thin. They accept POST /debug, append the raw request body to .debug/debug.log with a timestamp, and return ok.

Steps

Step 1: Understand the Bug

• Read the relevant code before changing anything.
• State 1-3 concrete hypotheses that runtime data can prove or disprove.
• Do not jump to a fix before collecting data unless the cause is already proven.

Step 2: Create the Debug Server

• Create .debug/ in the project under debug.
• Copy the matching bundled server from this skill's scripts/ directory to .debug/debug_server.js or .debug/debug_server.py in the project.
• For another language, create the smallest equivalent server at .debug/debug_server.<ext>.
• Keep the server thin: no schemas, dashboards, persistence, extra routes, or broad utilities.

Step 3: Start the Debug Server

Run it from the project root:

node .debug/debug_server.js 3333
python3 .debug/debug_server.py 3333

• The server is a long-running foreground process; start it in the background (or another terminal) so it does not block your shell.
• Use another port only if 3333 is occupied.
• Verify it with curl http://localhost:3333/health.
• Clear .debug/debug.log before reproduction if it already exists.

Step 4: Instrument the Code

• Add the fewest probes needed to test the hypotheses.
• Wrap every probe or probe block in matching debug region markers:

// #region DEBUG
fetch("http://localhost:3333/debug", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    event: "function-entry",
    traceId,
    value,
  }),
}).catch(() => {});
// #endregion DEBUG