@@ -1,112 +0,0 @@
1----
2-name: debug
3-description: "Debug mini-coder issues by analyzing session logs and database entries. Use when investigating errors, API failures, token usage, or session history. Triggers on: debug, logs, errors, API logs, session history, token usage."
4-allowed-tools: shell
5----
6-
7-# debug
8-
9-Use this skill when the user needs to debug mini-coder issues, investigate errors, or audit API logs and session history.
10-
11-## Database location
12-
13-```
14-~/.config/mini-coder/sessions.db
15-```
16-
17-SQLite database with a `logs` table keyed by `session_id`.
18-
19-## Schema
20-
21-```sql
22-CREATE TABLE logs (
23- id INTEGER PRIMARY KEY AUTOINCREMENT,
24- session_id TEXT NOT NULL REFERENCES sessions(id) ON DELETE CASCADE,
25- level TEXT NOT NULL, -- "api" | "error"
26- timestamp INTEGER NOT NULL, -- Unix ms
27- data TEXT NOT NULL -- JSON: { event: string, data: object }
28-)
29-```
30-
31-## Log levels
32-
33-| Level | When written |
34-| ------- | -------------------------------------------------- |
35-| `api` | Every LLM turn lifecycle event (see events below) |
36-| `error` | Caught exceptions, API failures, validation errors |
37-
38-## API event reference (post-v0.x)
39-
40-These are the events logged after the noise-reduction pass. Expect ~10 rows per turn:
41-
42-| Event | Key fields in `data` | Purpose |
43-| ---------------------------- | ------------------------------------------------------------ | --------------------------------- |
44-| `turn start` | `modelString`, `messageCount`, `reasoningSummaryRequested` | Start of a user→LLM turn |
45-| `turn complete` | `newMessagesCount`, `inputTokens`, `outputTokens` | End of turn with token usage |
46-| `turn error` | error fields (sanitized) | Turn failed |
47-| `turn context pre-prune` | `messageCount`, `totalBytes`, `roleBreakdown`, `toolResults` | Context snapshot before pruning |
48-| `turn context post-prune` | same shape as pre-prune | Context snapshot after pruning |
49-| `step finish` | `usage`, `finishReason`, `isContinued` | Each reasoning step within a turn |
50-| `stream chunk` (tool-call) | `type:"tool-call"`, `toolCallId`, `toolName`, `isError` | A tool was invoked |
51-| `stream chunk` (tool-result) | `type:"tool-result"`, `toolCallId`, `toolName`, `isError` | Tool result received |
52-
53-> Note: Older sessions in the DB may also contain `Provider Request`, `prompt caching configured`, and high-volume `stream chunk` events (`tool-input-delta`, `start-step`, etc.) — these were removed in a logging cleanup. The queries below filter for the current event set.
54-
55-## Useful shell queries
56-
57-**Recent sessions:**
58-
59-```bash
60-sqlite3 ~/.config/mini-coder/sessions.db "SELECT id, created_at, updated_at FROM sessions ORDER BY updated_at DESC LIMIT 10"
61-```
62-
63-**Log counts per level for a session:**
64-
65-```bash
66-sqlite3 ~/.config/mini-coder/sessions.db "SELECT level, COUNT(*) as n FROM logs WHERE session_id = '<id>' GROUP BY level"
67-```
68-
69-**All API events for a session (chronological):**
70-
71-```bash
72-sqlite3 ~/.config/mini-coder/sessions.db "SELECT datetime(timestamp/1000, 'unixepoch'), json_extract(data, '$.event'), data FROM logs WHERE session_id = '<id>' AND level = 'api' ORDER BY timestamp ASC"
73-```
74-
75-**Error logs only:**
76-
77-```bash
78-sqlite3 ~/.config/mini-coder/sessions.db "SELECT datetime(timestamp/1000, 'unixepoch'), data FROM logs WHERE session_id = '<id>' AND level = 'error' ORDER BY timestamp ASC"
79-```
80-
81-**Token usage across turns (input/output tokens per turn complete):**
82-
83-```bash
84-sqlite3 ~/.config/mini-coder/sessions.db "SELECT datetime(timestamp/1000, 'unixepoch'), json_extract(data, '$.data.inputTokens'), json_extract(data, '$.data.outputTokens') FROM logs WHERE session_id = '<id>' AND level = 'api' AND json_extract(data, '$.event') = 'turn complete' ORDER BY timestamp ASC"
85-```
86-
87-**Context pressure (pre vs post prune):**
88-
89-```bash
90-sqlite3 ~/.config/mini-coder/sessions.db "SELECT datetime(timestamp/1000, 'unixepoch'), json_extract(data, '$.event'), json_extract(data, '$.data.messageCount'), json_extract(data, '$.data.totalBytes') FROM logs WHERE session_id = '<id>' AND data LIKE '%prune%' ORDER BY timestamp ASC"
91-```
92-
93-**Tool calls in a session:**
94-
95-```bash
96-sqlite3 ~/.config/mini-coder/sessions.db "SELECT datetime(timestamp/1000, 'unixepoch'), json_extract(data, '$.data.toolName') FROM logs WHERE session_id = '<id>' AND level = 'api' AND data LIKE '%tool-call%' ORDER BY timestamp ASC"
97-```
98-
99-## Finding the current session ID
100-
101-Get the most recently active session:
102-
103-```bash
104-sqlite3 ~/.config/mini-coder/sessions.db "SELECT id FROM sessions ORDER BY updated_at DESC LIMIT 1"
105-```
106-
107-## Integration with mini-coder code
108-
109-- **`src/logging/context.ts`** — `logApiEvent(event, data)` and `logError(err, context)` write to the DB
110-- **`src/session/db/logs-repo.ts`** — `LogsRepo` class: `write()`, `getLogs()`, `deleteOldLogs()`, `deleteSessionLogs()`
111-- **`src/session/db/connection.ts`** — `getDb()` returns the singleton Bun SQLite instance
112-- Data is sanitized before write: strips `requestBodyValues`, `responseBody`, `responseHeaders`, `stack`