From debugging
Debug issues using a log-first methodology — reproduce the problem, collect structured JSONL logs, query them with DuckDB to find root cause, then fix. Use when asked to "debug this issue", "find why X fails", "trace the bug", "investigate error", "analyze logs", "why is X broken", "diagnose this failure", or "find the root cause". NOT for setting up logging (use logging-enablement instead).
How this skill is triggered — by the user, by Claude, or both
Slash command
/debugging:debug-with-logsThis skill is limited to the following tools:
The summary Claude sees in its skill listing — used to decide when to auto-load this skill
A systematic log-first debugging methodology. The core principle: **give AI full visibility into code execution via structured JSONL logs queried with DuckDB**.
A systematic log-first debugging methodology. The core principle: give AI full visibility into code execution via structured JSONL logs queried with DuckDB.
logging-enablement skilllogging-review agent.mcp.json)logging-enablement firstBefore touching any code:
Output: A clear problem statement — one sentence describing what's wrong.
A bug you can't reproduce is a bug you can't fix. Create concrete repro steps.
Reference: Reproduction Step Templates
Choose the appropriate template based on the system type:
Output: A script, command, or step list that reliably triggers the bug.
Trace level for the relevant components# Example: note the log file and line count before repro
wc -l app.log.jsonl # 1523 lines before
# ... run repro ...
wc -l app.log.jsonl # 1587 lines after → 64 new log lines
Output: Path to JSONL log file(s) covering the reproduction window.
Use DuckDB to query the JSONL logs at decision points. Start broad, then narrow down.
Reference: DuckDB Query Patterns
Query progression:
Overview — What happened during the repro window?
SELECT "@t", "@l", "@m" FROM read_json_auto('app.log.jsonl')
WHERE "@t" > '2025-06-15T14:30:00Z'
ORDER BY "@t";
Filter errors — Any errors or warnings?
SELECT "@t", "@l", "@m", "@x" FROM read_json_auto('app.log.jsonl')
WHERE "@l" IN ('Error', 'Warning', 'Fatal')
ORDER BY "@t";
Trace specific flow — Follow a request/operation through the system
SELECT "@t", "@logger", "@m" FROM read_json_auto('app.log.jsonl')
WHERE correlationId = 'req-12345'
ORDER BY "@t";
Decision point analysis — What values were in play at the failure point?
SELECT * FROM read_json_auto('app.log.jsonl')
WHERE "@logger" = 'OrderService'
AND "@t" BETWEEN '2025-06-15T14:31:00Z' AND '2025-06-15T14:32:00Z'
ORDER BY "@t";
Output: SQL query results showing the execution flow and failure point.
If Step 4 doesn't reveal the root cause:
Common gaps:
Iterate Steps 3-5 until root cause is visible in the logs.
The root cause must be provable from the logs, not guessed.
Format your findings as:
ROOT CAUSE: [One sentence description]
EVIDENCE:
- Log at [timestamp]: [what it shows]
- Log at [timestamp]: [what it shows]
- Gap/unexpected value: [what was expected vs actual]
AFFECTED CODE: [file:line]
npx claudepluginhub gautam-achieveai/claudeplugins --plugin debuggingCreates bite-sized, testable implementation plans from specs or requirements, with file structure and task decomposition. Activates before coding multi-step tasks.