Debug mode

Debug Mode

Use the evidence loop when the root cause is not proven. Avoid plausible fixes that only pass once.

Activation boundary

Reach for this skill — including autonomously, without waiting for the user to name it — when the user explicitly says diagnose/debug, or when a normal reproduction or inspection has not revealed the cause, especially for flaky, environment-specific, or production-only bugs.

Do not enter debug-mode for a compiler/type/lint/test error whose cause is directly in the output, a review finding that already specifies both cause and fix, an already-proven root cause, or when debug-mode is already active. Never re-invoke debug-mode from inside an active debug-mode run — continue the existing evidence loop.

Respect the user's verb: a diagnose-only request ends before the Fix step and applies no code change. A debug request, or an ordinary bug report with no explicit verb, continues through the Fix step as usual — do not withhold the fix just because the task didn't separately say "fix" or "correct".

Workflow

1. Understand. Done when symptoms, affected surface, expected behavior, actual behavior, and smallest reproduction path are known.
2. Feedback command. Done when, where practical, one command — a failing test, a curl script, a CLI run on a fixture, a headless-browser script, a replayed trace — has been run once and shown red on this bug's exact symptom: red-capable (asserts the symptom, not "didn't crash"), deterministic, fast, runnable unattended. Tighten it before moving on — sharper assert, narrower scope, pinned time/seed; for flaky bugs raise the reproduction rate (loop the trigger, add stress) until it's debuggable. When no such command is practical (auth-walled, user-specific, production-only), say so explicitly and rely on the instrumentation branch below — don't skip silently to code-reading.
3. Hypothesize. Done when 2-3 ranked hypotheses each name the observation that would confirm or reject it.
4. Instrument. Done when temporary structured logs distinguish the hypotheses without leaking secrets.
5. Reproduce. Done when the bug has been triggered and logs collected — via the feedback command when one exists. If the flow is auth-walled or user-specific, ask the user to reproduce and wait.
6. Analyze. Done when evidence confirms one hypothesis or rejects all current hypotheses explicitly.
7. Fix. Done when the smallest evidence-backed fix is applied, the feedback command (when one exists) has gone red → green — turned into a regression test first when a seam that exercises the real bug pattern exists — and all temporary instrumentation is removed.

Instrumentation Contract

Prefer structured events over prose logs. Each event should include enough context to tie one request or user action together without leaking secrets:

{
  "hypothesis_id": "H1",
  "event": "branch_selected",
  "request_id": "req_123",
  "session_id": "optional-session",
  "observed": { "key": "value" },
  "timestamp": "2026-05-11T15:00:00Z"
}

Use scripts/debug-server.mjs when a local HTTP collector is useful:

node <skill-dir>/scripts/debug-server.mjs --port 8765 --output <debug-events.jsonl>

The server accepts POST /log with a JSON body and writes JSONL. Confirm it is listening before adding app-side logging. Stop it after analysis, remove all instrumentation, and keep only the evidence summary in the final report.

If localhost is unreachable, log to the app's normal logger or a local file with the same fields.

Tag any plain-text fallback logs with one unique prefix (e.g. [DEBUG-a4f2]) so removal is a single grep — untagged logs survive cleanup.

Failure Modes

• Cannot reproduce locally: identify the missing condition, add targeted instrumentation, and ask the user to reproduce once.
• Auth-walled reproduction: prepare logging first, then wait for the user instead of guessing.
• User cannot reproduce: report the best-tested hypotheses and what evidence is still missing; do not invent a fix.
• Logs disprove every hypothesis: write new hypotheses from the evidence and instrument again.
• Instrumentation changes behavior: remove or reduce the instrumentation, then use a less invasive observation point.

Report Format

End with this shape:

## Symptoms
## Hypotheses Tested
## Evidence Collected
## Confirmed Root Cause
## Fix Applied
## Instrumentation Removed
## Residual Risk

If no fix was applied, say that under Fix Applied and name the missing evidence.