# Debug Mode

> Evidence-driven debugging for unresolved, flaky, environment-specific, or production-only bugs. Use when asked to diagnose or when normal inspection cannot prove the cause; skip obvious errors and already-proven causes.

- Skill: `hcaiano/debug-mode` (Agent Skill, multi-file: 3 files)
- Install (CLI): `npx skillmds@latest add hcaiano/debug-mode`
- Raw SKILL.md: https://api.skillmd.com/api/skills/hcaiano/debug-mode/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: hcaiano (https://skillmd.com/u/hcaiano)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/hcaiano/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:

```json
{
  "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:

```bash
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:

```markdown
## 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.