Initial project scaffold with uv

.opencode/skills/debug/SKILL.md

@@ -0,0 +1,67 @@
+---
+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.
+