vs-debug-mode

Files (5)

• SKILL.md
• openai.yaml · agents/
• debug_cleanup.js · scripts/
• debug_server.js · scripts/
• debug-mode.eval.ts · test/

SKILL.md (first lines)

# Debug

Find the root cause. Don't guess, don't patch symptoms.

```
Reproduce → Hypothesize → Investigate → Isolate → Fix → Verify → Prevent
```

## Phase 1: Reproduce

1. **Confirm the surface.** In a multi-app repo or multi-service system, pin
   which app, package, or deployment produced the failure before anything
   else. Match evidence identity — telemetry project, release string, URL,
   stack-frame paths — to one surface. Zero events or logs for the failure on
   the suspected surface is disconfirming evidence, not neutral: pick the
   surface the evidence actually points to, and only fix a surface the
   evidence places the failure on.
2. **Get the exact error.** Full stack trace, exit code, failing assertion. Not a summary.
3. **Reproduce it.** If it passes now, it's intermittent — note that.
4. **Minimize the reproduction.** Smaller repro = faster investigation.
5. **Build the feedback loop.** Before deep analysis, create the fastest command, script, browser flow, curl call, fixture replay, bisect, or temporary harness that flips from fail to pass when the bug is fixed. Static inspection alone is not a reproduction. For memory, performance, or crash-under-load bugs, that harness measures the resource (heap/RSS sampling, constrained limits that simulate the target device) — a console-log server is the wrong instrument for resource pressure.

If the bug is intermittent, raise the reproduction rate before fixing: run the loop repeatedly, add stress/parallelism, narrow timing windows, or report the observed pass/fail rate. A single lucky pass is not evidence.

## Phase 1b: Start Log Server (frontend/UI bugs only)

**Trigger:** the bug is in a browser, needs runtime evidence, or you'd normally say "add console.log and check DevTools."

If the bug is backend/logic/CI, skip to Phase 2.

```bash
node <skill-dir>/scripts/debug_server.js /path/to/project &
```

Create session:
```bash
curl -s -X POST http://localhost:8787/session -d '{"name":"fix-null-userid"}'
```
Returns `{"session_id":"fix-null-userid-a1b2c3","log_file":"..."}`. Save the `session_id`.

**If port 8787 busy:** `lsof -ti :8787 | xargs kill -9` then restart.

## Phase 2: Hypothesize

Generate 3-5 specific, testable hypotheses. Order by likelihood. Each hypothesis includes a **prediction**: if this cause is true, what observation or change should happen?

```
H1: userId is null because caller doesn't check return value
    Prediction: entry log shows caller receives null before any downstream mutation
    Test: add assertion at function entry / log at entry

H2: Config file missing in CI but present locally
    Prediction: file existence differs between local shell and test context
    Test: check if file exists in test context

H3: Race condition — async op completes before setup
    Prediction: timestamps show setup finishes after the first read
    Test: add ordering / log timestamps at both points
```

**Common root causes:** state (wrong/missing/stale/mutated), timing (race/async/timeout), environment (missing file/wrong path/config), types (boundary coercion/null), logic (off-by-one/wrong condition), integration (contract mismatch/schema drift).

## Phase 3: Investigate

Track each attempt explicitly:

```
[DEBUG-1]: Checked userId null path → REJECTED, userId is populated
[DEBUG-2]: Checked race condition on init → INCONCLUSIVE, timing looks fine
[DEBUG-3]: Checked config loading → REJECTED, config present in all envs
```

After 3 failed attempts (`[DEBUG-3]` reached with no CONFIRMED hypothesis): stop
guessing. You are stuck. Escalate — request external research, ask the user for
more context, or search for similar issues in the project/ecosystem. Do not
continue generating hypotheses from the same evidence.

For each hypothesis (most likely first):

### Without log server (backend/logic/CI)

- **Code path tracing:** find where the value comes from, trace callers, check data flow
- **Test isolation:** run just the failing test with verbose output
- **State inspection:** trace data backward from failure to origin
- **Diff analysis:** `git log --oneline -20 -- <files>` / `git diff <last-good>..HEAD`
- **Environment comparison:** versions, env vars, file existence

### With log server (frontend/UI)

Instrument code to test all hypotheses. Wrap in `// #region debug` ... `// #endregion`.

**JavaScript/TypeScript:**
```javascript
// #region debug
const SESSION_ID = 'REPLACE_WITH_SESSION_ID';
const DEBUG_LOG_URL = 'http://localhost:8787/log';
const debugLog = (msg, data = {}, hypothesisId = null) => {
  const payload = JSON.stringify({
    sessionId: SESSION_ID, msg, data, hypothesisId,
    loc: new Error().stack?.split('\n')[2],
  });
  if (navigator.sendBeacon?.(DEBUG_LOG_URL, payload)) return;
  fetch(DEBUG_LOG_URL, { method: 'POST', body: payload }).catch(() => {});
};
// #endregion
```

**Python:**
```python
# #region debug
import requests, traceback
SESSION_ID = 'REPLACE_WITH_SESSION_ID'
def debug_log(msg, data=None, hypothesis_id=None):
    try:
        requests.post('http://localhost:8787/log', json={
            'sessionId': SESSION_ID, 'msg': msg, 'data': data,
            'hypothesisId': hypothesis_id, 'loc': traceback.format_stack()[-2].strip()
        }, timeout=0.5)
    except: pass

From vltansky/vs, MIT.

More from vltansky/vs