---
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

Analyse Claude agent stream logs — the `claude-agent-stream-*.log` files generated by the platform. 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 to retrieve logs. From the dev machine (SSH), use the shell counterpart:

```bash
# Retrieve session timeline (all log types, including server.log) — sessionKey is the handle
sshpass -p 'password' ssh admin@<hostname>.local "~/<installDir>/platform/scripts/logs-read.sh <sessionKey>"

# Tail the most recent stream log
sshpass -p 'password' ssh admin@<hostname>.local "~/<installDir>/platform/scripts/logs-read.sh --tail system 200"
```

To go from a `conversationId` (visible in the admin UI) to a `sessionKey` (the log filter handle), see the **Conversation Identification** section in `references/analysis-patterns.md`.

## Boundaries

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

## References

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