melech-debug-mode

Files (10)

• README.md
• SKILL.md
• collector.py · assets/
• melech-auto-before-after.png · assets/
• melech-behind-scenes-debug.png · assets/
• melech-what-debug-mode.png · assets/
• debug_session.py · scripts/
• dm.sh · scripts/
• install-dm.sh · scripts/
• test_debug_session.py · tests/

SKILL.md (first lines)

# Debug Mode

Follow this protocol for the user's requested workflow:

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

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

```bash
npm install -g portless
```

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

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

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

From AdirD/agent-shell-hamelech, MIT.

More from AdirD/agent-shell-hamelech