interactive-debugging

Solid

Use this skill when debugging runtime behavior requires live data from the running app, temporary instrumentation, or hypothesis verification through logs. Trigger for async timeouts, stale or incorrect state updates, race conditions, event ordering bugs, intermittent failures, browser/client behavior that static inspection cannot explain, or any issue where the agent should create a local debug HTTP server, insert temporary probes, ask the user to reproduce, inspect .debug/debug.log, then remove all debug instrumentation and assets.

Code & Development 16 stars 0 forks Updated 3 days ago MIT

Install

View on GitHub

Quality Score: 80/100

Stars 20%

Recency 20%

100

Frontmatter 20%

Documentation 15%

100

Issue Health 10%

License 10%

100

Description 5%

100

Skill Content

# 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: ```bash 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 a...