Motel Debug

Motel Debug

You are in debug mode. Debug with runtime evidence, not guesswork.

Agents guess based on code alone. You need actual runtime data. Motel is the local OpenTelemetry server that collects traces and logs — use it as your evidence loop.

Default local server details:

• Base URL: http://127.0.0.1:27686
• OTLP traces: POST /v1/traces
• OTLP logs: POST /v1/logs
• Query API: GET /api/*
• OpenAPI: GET /openapi.json
• Header: Content-Type: application/json
• Auth: none by default

If the user provides a different motel URL, use that instead of the default.

Workflow

1. Verify motel is running — and start it if not

Check GET /api/health. If it returns 200, continue.

If it fails (connection refused, timeout, non-200), motel isn't running. Start it as a background daemon — do not launch the TUI, which is interactive and will block your shell:

motel start

motel start ensures the machine-global managed daemon is running, writes runtime files under ${XDG_STATE_HOME:-~/.local/state}/motel/, and returns a JSON status blob. It is idempotent and shared across local projects. If motel isn't on PATH, fall back to bunx @kitlangton/motel start.

After starting, re-check GET /api/health (may take 1–2s to become ready). If it still fails, read ${XDG_STATE_HOME:-~/.local/state}/motel/daemon.log for the error and surface it to the user.

Other lifecycle commands, for reference:

motel status   # JSON status (running? pid? originating workdir?)
motel stop     # stop the shared managed daemon for all local projects

Discover reporting services with GET /api/services when needed.

2. Generate hypotheses

Before touching any code, generate 3-5 specific hypotheses about why the bug occurs. Be precise — "the cache key doesn't include the user ID" is better than "something is wrong with caching."

3. Instrument with tagged debug blocks

Add the minimum instrumentation needed to confirm or reject all hypotheses in parallel. Every debug block must:

• Be wrapped in #region motel debug / #endregion motel debug markers
• Include a debug.hypothesis attribute linking it to a specific hypothesis
• Use whatever tracing/logging mechanism the codebase already has (spans, structured logs, annotations — not raw fetch calls)

Tag every piece of debug instrumentation with structured attributes so you can query it later. Reuse these keys:

Choose log placements based on your hypotheses:

• Function entry with parameters
• Function exit with return values
• Values before and after critical operations
• Branch execution paths (which if/else ran)
• State mutations and intermediate values
• Suspected error or edge-case values

Guidelines:

• At least 1 instrumentation point is required; never skip instrumentation
• Do not exceed 10 — if you think you need more, narrow your hypotheses
• Typical range is 2-6

4. Reproduce the issue

• If a failing test exists, run it directly
• If reproduction is straightforward (CLI command, curl, simple script), write and run it yourself
• Otherwise, ask the user to reproduce — provide clear numbered steps and remind them to restart if needed
• Once a reproduction pathway is established, reuse it for all subsequent iterations

5. Analyze evidence

Query motel for the debug instrumentation:

curl "http://127.0.0.1:27686/api/spans/search?service=<service>&attr.debug.hypothesis=<id>"
curl "http://127.0.0.1:27686/api/logs/search?service=<service>&attr.debug.session=<session>"
curl "http://127.0.0.1:27686/api/traces/search?service=<service>&attr.debug.hypothesis=<id>"

For each hypothesis, evaluate: CONFIRMED, REJECTED, or INCONCLUSIVE — cite specific spans, logs, or attribute values as evidence.

6. Fix only with evidence

Do not fix without runtime evidence. When you fix:

• Keep all debug instrumentation in place — do not remove it yet
• Make the fix as small and targeted as possible
• Reuse existing architecture and patterns; do not overengineer