---
name: debug
description: Diagnose frozen, slow, or misbehaving sessions by reading debug logs and system state
compatibility: opencode
metadata:
  workflow: diagnostics
---

## What I do

I diagnose problems with the current session — freezes, slowness, errors, or unexpected behavior — by reading debug logs and checking system state.

## How to use me

1. **Find the debug log.** Check these locations in order:
   - `~/.local/share/opencode/logs/` (Linux)
   - `~/Library/Application Support/opencode/logs/` (macOS)
   - `~/.config/opencode/logs/` (fallback)
   - Environment variable `OPENCODE_LOG_DIR` if set
   - Any `.log` files in the project root or `.opencode/` directory

2. **Read the tail of the log** (last 50-100 lines, or last 64KB max). Do not read the entire log file — it can be enormous.

3. **Check system state:**
   - Is the process still running? (`ps aux | grep opencode`)
   - Is CPU usage abnormally high?
   - Is memory usage growing unbounded?
   - Are there zombie or defunct child processes?
   - Is the git repo in a weird state (merge conflict, detached HEAD, locked index)?

4. **Identify the problem category:**
   - **API errors** — rate limits, auth failures, model errors, timeout
   - **Tool errors** — command failures, permission denials, file not found
   - **Session freeze** — no output for extended period, hung child process
   - **Performance** — slow responses, high token usage, context window overflow
   - **Configuration** — missing API key, wrong model, broken settings

5. **Report findings with evidence.** Quote relevant log lines. Do not speculate without log evidence.

## Investigation rules

- Reproduce before you reason. Never guess at a cause without first confirming the bug.
- Read logs, don't hallucinate. Quote specific log lines with timestamps.
- If you cannot reproduce, report what you tried and ask for more information.
- If the problem is upstream or environmental, say so explicitly.

## Output format

### Symptoms
What the user reported or what I observed.

### Log Evidence
Relevant log lines (quoted, with timestamps).

### Diagnosis
What is wrong and why.

### Recommended Fix
Specific steps to resolve the issue.

### Escalation
If the problem is a bug in opencode itself, note the version, reproduction steps, and suggest filing an issue at https://github.com/anomalyco/opencode/issues.

## When to use me

Use this when a session is frozen, slow, throwing errors, or behaving unexpectedly. Do not use for general code debugging — this skill is for diagnosing the tool itself, not the user's code.