Debug Mode

Follow this protocol for the user's requested workflow:

choose browser driver → attach if autopilot → define one complete attempt
→ start collector → add probes → prove probes loaded → run E2E → read evidence
→ act on evidence → rerun E2E if code changed → clean up

The E2E boundary is the local UI in a browser. A unit, integration, AI, or test-harness run never counts as E2E, even when it uses a real model, tool, sandbox, filesystem, or backend. Neither does a direct call, script, synthetic request, or isolated endpoint.

Do not create or run a test harness before the first browser attempt. Tests and direct calls are supplemental diagnostics only after browser reproduction. If the requested behavior cannot be exercised through a local UI, say this skill does not provide its E2E path; do not relabel a harness as E2E.

1. Choose The Driver

• Use autopilot by default for every local UI workflow.
• User explicitly says they will drive, hold the wheel, or use proceed → manual.
• The user denies browser control, the target tab is ambiguous or unsafe, the target appears to be production, or attach remains unavailable after retry → manual.

Do not ask the user to choose for an ordinary local UI.

For autopilot, read the installed melech-live-browser/SKILL.md, show its Chrome consent notice, and begin its attach flow before any diagnostic shortcut. If it is missing, offer:

npx skills add https://github.com/AdirD/agent-shell-hamelech --skill melech-live-browser

Ask whether to install it or switch to manual. Never substitute another browser or profile.

Autopilot always starts by asking the user to enable remote debugging at chrome://inspect/#remote-debugging and click Allow when Chrome prompts. If attach fails, repeat that request and retry once. Manual is a fallback only after that retry fails.

Manual still uses the running local UI and the same probes. Give the user the reset, actions, and deciding outcomes, ask them to reply exactly proceed after one reproduction, then stop and listen. Read the evidence only after that reply.

2. Define One Attempt

State:

• the reset and starting state
• the exact actions
• the observable outcomes that decide the user's request
• at most five probes needed to distinguish those outcomes

3. Start The Collector

Locate this installed skill directory and confirm python3 and portless exist. If Portless is missing, stop and request:

npm install -g portless

Run portless doctor when first-use setup is needed, then:

source <skill-dir>/scripts/dm.sh
dm start

dm is the sourced shell function for python3 <skill-dir>/scripts/debug_session.py. If a later step reports dm undefined, re-source dm.sh or call that path directly.

Command	Use
dm start	start one temporary collector
dm status <session-dir>	that session's metadata and process liveness
dm logs <session-dir> [--run ID] [--after-seq N] [--tail N]	read compact JSONL, one complete event per line
dm logs <session-dir> --pretty	human-readable multi-line events
dm stop <session-dir>	tear down that session
dm doctor --once	JSON snapshot of every live session

Always pass --once to doctor: bare dm doctor (and bare dm) opens a curses TUI for the user's own terminal and will hang or crash a non-interactive shell.

dm start prints the facts every later step needs: session_id, session_dir, log_endpoint, health_url, events_file, and backend_host/backend_port. Save them, then confirm the collector answers before editing application code:

curl -s "<health_url>"    # {"ok":true,"entries":0}

health_url and log_endpoint route through Portless. If that route is unreachable from the runtime executing a probe, the same collector answers on http://<backend_host>:<backend_port>; swap only the origin and keep the /log/<token> path from log_endpoint.

Keep the collector local; never enable LAN mode, tunnels, Tailscale, Funnel, ngrok, or other remote exposure.

4. Add Probes

Derive placement from the deciding outcomes: the branch that should or should not run, the value immediately before a transformation, the boundary input and output, and the error path. Instrument whichever layer owns the question — for a browser workflow that means page or component state for rendering and interaction, and server handlers for persistence, validation, and integration.

For each already-running target, record the available freshness baseline that fits its lifecycle: process start, build identity, or build/reload log cursor. One-shot source-loaded commands run after the edit need no prior baseline.

POST one small JSON object per observation to log_endpoint exactly as returned (it embeds the session token):

{
  "run": "run-1",
  "probe": "checkout-before-submit",
  "hypothesis": "save commits exactly once",
  "data": { "isDisabled": true, "itemCount": 2 }
}

Fire and forget, so a collector failure cannot change product behavior:

// DEBUG_MODE:<session-id>:checkout-before-submit
void fetch("<log-endpoint>", {
  method: "POST",
  headers: { "content-type": "application/json" },
  body: JSON.stringify({
    run: "run-1",
    probe: "checkout-before-submit",
    hypothesis: "save commits exactly once",
    data: { isDisabled, itemCount: items.length },
  }),
}).catch(() => {});

Adapt the idiom to the target language while keeping the payload shape, the marker comment, the narrow field selection, and the swallowed failure. Send booleans, counts, enum values, IDs already safe in development, and short summaries — never credentials, tokens, cookies, authorization headers, personal data, full bodies, or unrelated state.

Because a fire-and-forget probe cannot see a refusal, prove collector delivery once with the real payload shape before the attempt:

curl -s -X POST "<log_endpoint>" -H 'content-type: application/json' \
  -d '{"run":"run-0","probe":"delivery-check","data":{"ok":true}}'
# {"accepted":true,"seq":1}

Any other response means the collector refused the event rather than the code path never running: a missing content-type, a non-object or malformed body, a payload over 64 KB, a wrong URL or token, or sensitive_field_rejected. That last one drops an event whose key — at any nesting depth, ignoring case and hyphens — exactly matches a credential name such as token, secret, password, cookie, authorization, api_key, or access_token. Rename the field descriptively (hasSessionToken) instead of removing the observation.

Mark every temporary edit DEBUG_MODE:<session-id>:<probe-id> and track touched files. Run only the cheapest compile, type, or syntax check needed to prove the instrumentation is valid; probe events from that check are not E2E evidence. Do not create a test file or harness to load probes. Load them in the same dev services that serve the browser workflow.

Before E2E, prove each long-running or prebuilt target loaded the probe. Require evidence produced after the probe edit and tied to that source or artifact: a new build/HMR/restart marker for the edited target, a source-loaded process started after the edit, or a probe-specific load event. For prebuilt runtimes, verify both that the artifact was built after the edit and that the process loaded it. A changing terminal mtime or old restart text does not prove freshness. A Jest, Vitest, AI-harness, or other test process does not prove that the browser-serving runtime loaded the probe.

If the runtime is stale, an existing trace, persisted input, audit record, or other authoritative boundary record may replace the probe only when it captures the same deciding fact. Name the exact record; app prose and inferred UI behavior do not qualify.

Otherwise restart only the target service when safe. If the user owns that process or a restart may interrupt active work, stop and ask:

<service> is still running pre-probe code. Rebuild or restart it, then tell me and I'll continue.

A successful shell delivery check proves only the collector works.

5. Run The Browser Attempt

Use run-1 initially and increment the run ID for every retry, supplemental diagnostic, and post-change verification. After each complete attempt, read:

dm logs <session-dir> --run <run-id>

Every line is an envelope: your object under payload, plus seq and received_at. Default output is JSONL: each line is one complete JSON object and can be parsed independently. Use --after-seq to see only what the newest attempt added, --tail when a run is noisy, and --pretty only for human reading.

Autopilot

Use melech-live-browser to select the existing app tab, snapshot it, and drive exactly one complete attempt, then read that run. Correlate console or network evidence through live browser only when a stated outcome needs it, and never conclude from a snapshot alone. Do not ask for proceed. If attach or tab selection fails, switch to manual.

Manual

Tell the user manual mode is active, give the defined reset, actions, and deciding outcomes, and ask them to reply exactly proceed after one attempt. Then stop. Read that run only after proceed.

6. Act On Evidence

Cite the event sequence and values that support the result. Do not infer cause from correlation.

• Use the evidence to carry out the user's requested next action without broadening it.
• Evidence is incomplete → revise the minimum probes and repeat with a new run ID through the same E2E driver.
• Unexpectedly no events from a probe still in the evidence plan → first confirm the instrumented runtime rebuilt or restarted after the probe edit. Then confirm the collector is serving with the health_url curl or dm doctor --once (dm status only reports process liveness), and repeat the delivery check. The collector already allows cross-origin posts, so for page-side probes suspect the app's CSP connect-src or an unreachable route; repair, then repeat E2E.
• Code changed → keep relevant probes and repeat the same E2E workflow before cleanup.

Supplemental Diagnostics

Only after the first browser E2E attempt, focused tests, direct calls, ad hoc diagnostic scripts, endpoint requests, or synthetic requests may isolate a narrower question. Label them supplemental with separate run IDs; they never satisfy an E2E gate or post-change verification.

7. Clean Up

After a conclusive E2E result with no code change, successful post-change E2E verification, or abort:

1. Remove every DEBUG_MODE:<session-id>: probe and debug-only change.
2. Search touched files for DEBUG_MODE: and inspect the diff.
3. Stop browser operations without closing user-owned tabs.
4. Run dm stop <session-dir> and confirm removed: true.

If teardown fails, report the session directory and PID; never broad-kill or run broad Portless cleanup. If interrupted, recover the saved session_dir with dm status, dm logs, or dm doctor --once, then finish or abort through this cleanup.