68 lines
2.5 KiB
Markdown
68 lines
2.5 KiB
Markdown
---
|
|
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.
|
|
|