---
name: stream-log-review
description: >
  Analyse a Claude agent stream log file for errors, warnings, and anomalies.
  Produces a structured diagnostic report with session-by-session breakdown,
  root-cause analysis for known patterns, and cost/usage summary.
  Trigger phrases: "review logs", "stream log", "log errors", "log review",
  "what went wrong", "diagnose the log", "log report".
---

# Stream Log Review

Invoked by the admin agent directly.

Analyse Claude agent stream logs — the `claude-agent-stream-{sessionId}.log` files generated by the platform. Each file is scoped to exactly one conversation; a resumed conversation accumulates in one file across multiple process lifetimes, delimited by `[spawn]` / `[process-exit]`. Pre-conversation events (CDP auth-poll, module-init warnings) live in `preconversation-claude-agent-stream-{YYYY-MM-DD}.log` — a separate file per UTC day, read only when investigating boot-time failures.

Parse the log, identify problems, attempt diagnosis, and produce a structured report.

## When to Activate

- Admin asks to review, diagnose, or analyse a stream log
- A log file path is provided for analysis
- Admin asks what went wrong in a session or across sessions

## What a Good Report Looks Like

- Covers every session in the log, segmented by session boundaries
- Every error and warning is classified by severity with a root-cause diagnosis where patterns are known
- Errors that repeat across sessions are grouped and counted, not listed individually
- Causal chains are identified (e.g. DNS failure leading to retry loop leading to context overflow)
- Cost and token usage are summarised per session and in aggregate
- Recommendations are actionable — grouped by bugs to fix, infrastructure issues, and agent behaviour problems
- A non-technical admin can scan it for severity; a developer can use it to prioritise fixes

## Log Retrieval

On the Pi, use the `logs-read` MCP tool with `sessionId` to retrieve a single conversation's log. From the dev machine (SSH), use the shell counterpart:

```bash
# Read a single conversation's stream log (primary mode)
sshpass -p 'password' ssh admin@<hostname>.local "~/<installDir>/platform/scripts/logs-read.sh <sessionId> system"

# Tail the most-recently-active stream log (any conversation)
sshpass -p 'password' ssh admin@<hostname>.local "~/<installDir>/platform/scripts/logs-read.sh --tail system 200"

# Legacy: grep sessionKey across all log files (backward compat)
sshpass -p 'password' ssh admin@<hostname>.local "~/<installDir>/platform/scripts/logs-read.sh --grep <sessionKey>"
```

The `sessionId` is visible in the admin UI and appears on every `[spawn]` / `[process-exit]` line in the log itself. A single `logs-read.sh <sessionId> system` returns the full conversation-scoped record — no grep filter required, no cross-file correlation.

## What to Look For

- `[tool-wait]` lines every 5 s between `[tool-use]` and `[tool-result]` — distinguishes API silence from tool-internal stall.
- `[tool-wait-diag]` at 15 / 30 / 45 / 60 s — confirms DNS/TCP/HTTP health across a stall window (not just at the timeout moment).
- `[tool-wait-proc]` at 30 s — subprocess open FDs, sockets by TCP state, RSS.
- `[subproc-stderr]` — line from the main Claude Code subprocess's stderr. Today the CLI is a bundled Bun binary that ignores Node's `NODE_DEBUG`, so this channel is normally silent — see `[subproc-debug-unavailable]` below. MCP server stderr lines arrive separately as `[mcp:<server>]`.
- `[subproc-stderr-tee-attached]` / `[subproc-stderr-tee-detached]` — lifecycle of the main-subprocess stderr tee. `bytes=0 lines=0` on detach means the tee worked but the subprocess emitted nothing. Absence of both markers next to a `[spawn]` means the tee infrastructure is broken — escalate.
- `[subproc-debug-unavailable]` — one line per spawn, `reason=bundled-bun-binary-ignores-node-debug`. This is the documented reason `[subproc-stderr]` lines are normally absent for the main subprocess. Treat its absence as a regression, not its presence as a problem.
- `[tool-failure-diag]` — one-shot probe on the failure path; complements the mid-flight `[tool-wait-diag]` with end-of-wait network state.
- `[mcp-tee-attach]` / `[mcp-tee-skip]` / `[mcp:<server>]` — MCP server stderr routed into the stream log; a missing attach marker explains missing server diagnostics.
- `[tool-result] error=true output="WEBFETCH_CANNOT_READ_JS_SPA: …"` — a WebFetch dispatch was short-circuited by the SPA preflight hook. The URL is a JS-SPA shell that WebFetch cannot extract content from. The agent should have responded to the user naming the failure and asking for a paste or screenshot; if instead an `[agent-dispatch]` (Playwright, research-assistant) follows immediately, the loud-failure guidance in IDENTITY.md did not land. The hook's per-invocation decision trail lives in `{accountDir}/logs/webfetch-preflight.log` (one `[webfetch-preflight] verdict=…` line per probe).

## Boundaries

- This skill analyses logs. It does not fix the bugs it finds — that's a separate task.
- Applies to `claude-agent-stream-{sessionId}.log` files only. SSE event logs and stderr logs are handled by `logs-read` directly.
- Does not modify or rotate log files.
- Does not correlate across conversations — each report covers a single conversation's log.

## References

Load `references/analysis-patterns.md` for the event taxonomy, error classification patterns, diagnosis heuristics, and report format template.