rich-print/.opencode/skills/debug/SKILL.md

name, description, compatibility, metadata

name	description	compatibility	metadata
debug	Diagnose frozen, slow, or misbehaving sessions by reading debug logs and system state	opencode	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.