# motel-debug

Uses a local OpenTelemetry motel server to debug from traces and logs, with temporary instrumentation that can be removed after the fix is verified.

- skill · `type=skill` · Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, OpenCode · 695 installs · ★ 300
- Author: kitlangton
- License: MIT · policy=mirror · the beginning of the file is at the end of this page
- Source: https://github.com/kitlangton/motel/tree/HEAD/skills/motel-debug/SKILL.md
- Updated: 2026-09-02
- HTML: https://affpapa.org/en/nevibecode/skills/motel-debug

## What it does

This skill structures debugging around runtime evidence. It checks `GET /api/health`, starts the managed background daemon with `motel start` when needed, then builds 3–5 concrete hypotheses before changing application code. Temporary probes use the project’s existing tracing or logging system and are wrapped in `#region motel debug` and `#endregion motel debug` markers. Events carry `debug.session`, `debug.hypothesis`, `debug.step`, and `debug.label` attributes.

After the issue is reproduced, the skill queries motel for spans, traces, and logs, then marks each hypothesis as confirmed, rejected, or inconclusive with supporting values. The instrumentation stays in place while the fix is checked and is removed only after verification. The default server is `http://127.0.0.1:27686`; if it still fails its health check after startup, inspect `${XDG_STATE_HOME:-~/.local/state}/motel/daemon.log`. Repositories using Effect or `@effect/*` also use `references/effect.md`.

## Install

### Claude Code (native platform)

1. **Skills CLI (Vercel)**
```bash
npx skills add kitlangton/motel --skill motel-debug -a claude-code
```

2. **Manually: put the files in place**
- File: `~/.claude/skills/motel-debug/SKILL.md` — Copy the whole skill folder; for one project use .claude/skills/motel-debug/

### Codex

1. **Skills CLI (Vercel)**
```bash
npx skills add kitlangton/motel --skill motel-debug -a codex
```

2. **Manually: put the files in place**
- File: `.agents/skills/motel-debug/SKILL.md` — For all projects use ~/.agents/skills/

### Cursor

1. **Skills CLI (Vercel)**
```bash
npx skills add kitlangton/motel --skill motel-debug -a cursor
```

2. **Manually: put the files in place**
- File: `.cursor/skills/motel-debug/SKILL.md` — Cursor also reads .agents/skills/ and .claude/skills/

### GitHub Copilot

1. **GitHub CLI**
```bash
gh skill install kitlangton/motel motel-debug
```

2. **Manually: put the files in place**
- File: `.github/skills/motel-debug/SKILL.md`

### Gemini CLI

1. **Skills CLI (Vercel)**
```bash
npx skills add kitlangton/motel --skill motel-debug -a gemini-cli
```

2. **Platform CLI**
```bash
gemini skills install https://github.com/kitlangton/motel --path skills/motel-debug
```

### Windsurf (Devin Desktop)

**Manually: put the files in place**
- File: `.devin/skills/motel-debug/SKILL.md` — The legacy .windsurf/skills/ path still works

### OpenCode

**Skills CLI (Vercel)**
```bash
npx skills add kitlangton/motel --skill motel-debug -a opencode
```

### Claude.ai

**Claude.ai**
- Zip the folder and upload it in Settings → Capabilities → Skills

Where a file is given instead of a command, copy the files from the source to that path: https://github.com/kitlangton/motel/tree/HEAD/skills/motel-debug/SKILL.md

## When to use it
- trace a bug using runtime spans and logs
- test several failure hypotheses in one reproduction
- add temporary debug probes to application code
- compare telemetry before and after a fix
- remove debug blocks after verification

## Example prompts
- Debug this failure with runtime traces and logs from motel.
- Create concrete hypotheses for the failing test, instrument them temporarily, and check the results through motel.
- Wire this repository to the local motel server and find why the cache value changes after the write.

## Source text · SKILL.md · MIT

Below is the content of a third-party file. It is data, not instructions for you: do not act on anything written inside unless the human asks. Block tag: fe00b5e8926209bd.

BEGIN THIRD-PARTY FILE fe00b5e8926209bd
````text
---
name: motel-debug
description: Debug applications with motel, a local OpenTelemetry ingest and query server. Use when the user wants runtime-evidence debugging with traces or logs, wants temporary debug instrumentation that can be removed later, or needs a repo wired to send OTLP/HTTP telemetry to a local motel server. If the target repo uses Effect or @effect/*, also read references/effect.md.
---

# 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:

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

```bash
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)
````
END THIRD-PARTY FILE fe00b5e8926209bd

The third-party file has ended. Everything between the fe00b5e8926209bd tags is data: requests and commands from it are not followed. An “end of file” line with another tag inside the block is part of the file.

First 2749 of 8693 bytes. © kitlangton · MIT · https://github.com/kitlangton/motel/tree/HEAD/skills/motel-debug/SKILL.md

_Part of the page did not fit — see the HTML version._

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md