/debug

name: debug
description: Debug bugs in Houston. NEVER guess. Read log files first (dev panes + agent runtime). Add targeted logging if not enough info. Never ask user to copy-paste terminal output.

/debug

**NEVER guess.** Logs always faster than speculation.

The rule

Bug occurs + fix not obvious → 1. **Read log files FIRST.** They have all errors. 2. Diagnose from ACTUAL error in logs. Not assumptions. 3. Not enough info? Add a targeted `logger.debug()` at the branch point. 4. **Never** ask user to copy-paste terminal output. Read logs directly.

Log locations

`HOUSTON_HOME` is `~/.dev-houston` in the dev loop, `~/.houston` in production.

| Layer | File | Contents | |-------|------|----------| | Dev stack panes | `~/.dev-houston/logs/dev-<pane>.log` (previous boot kept as `.prev`) | Host, gateway, control-plane: everything an mprocs pane prints, and the only place they print. The pane's scrollback dies with the stack; this file does not | | Agent runtime | `<HOUSTON_HOME>/workspaces/<ws>/<agent>/.houston/runtime/runtime.log` | The agent loop: provider requests, tool calls, and the FULL provider error. The single best source for a turn that went wrong | | Tauri shell | `<HOUSTON_HOME>/logs/backend.log.<date>` | Desktop shell only: window, sidecar spawn, OS-native commands. Daily rolling, latest = current file | | Frontend | `<HOUSTON_HOME>/logs/frontend.log` | JS console.error/warn, React crashes, native command failures | | Cloud dev pods | `~/.dev-houston-cloud/<org>/<slug>/workspaces/…` | One tree per dev engine pod, each with the same per-agent `runtime.log` |

If no log covers the problem, don't guess: give the user exact steps to run the app so the logs get generated, then read them.

Logging APIs

import { logger } from "@/lib/logger";
logger.error("fetch failed", { url, status });
logger.warn("retry", { attempt });
logger.info("user clicked");
logger.debug("render", { props });

`console.error` + `console.warn` are patched to auto-write to `frontend.log`. The host and runtime log through their own structured loggers; the Tauri shell is the one Rust surface, `tracing::{info,warn,error,debug}!` → `backend.log` (default level `info`, override with `RUST_LOG=debug,crate_name=trace`).

Bug reports

"Report bug" button on error toasts auto-attaches last 50 lines from both logs.

Adding logging when logs are insufficient

1. Identify suspected code path 2. Add `logger.debug("descriptive message", { relevant_vars })` at branch points 3. Ask user to reproduce 4. Read updated logs 5. Fix w/ actual knowledge

Don't leave debug logs in. Remove after fix.

Anti-patterns

• ❌ "Let me try X and see if it fixes it" → guess
• ❌ "Can you share the terminal output?" → read the logs yourself
• ❌ `unwrap()` to silence compile errors → hides real failure
• ❌ `let _ = x.await` on ops that can fail → silent failure (banned by style rules)

Quick checks

# Tail the host pane
tail -f ~/.dev-houston/logs/dev-host.log

# The agent that misbehaved
tail -100 ~/.dev-houston/workspaces/Personal/<Agent>/.houston/runtime/runtime.log

# Grep for pattern
grep -i error ~/.dev-houston/logs/dev-gateway.log

Use the dedicated Read tool, not bash `cat`/`head`/`tail`, when operating through Claude Code.