| name | triage |
| description | Quick health check at the *menu* level — either scan recent plays for ones needing attention (no target given, or "what's broken right now"), or drill the named player's current session for state + recent failures. Surfaces 3-6 worst signals with timestamps and a suggested next skill. Invoke when the user says "triage X", "what's wrong with X", "how's X doing", "any plays needing attention", "scan plays", "what's broken right now", or asks for a summary of recent failures. Does NOT drill into individual events (use `investigate` for that). |
| last_reviewed | "2026-05-19T00:00:00.000Z" |
Triage — scan plays OR diagnose one player
Read first: top of the file at ~/.local/bin/harness is the harness CLI. If which harness fails, run make harness-cli in the repo root.
Conventions: this skill follows the cross-skill rules in .claude/skills/CONVENTIONS.md. The load-bearing ones for triage: lead every shell command with the tool name (no VAR=… / cd … / echo "header"; … prefixes); tag causal claims confirmed/refuted/needs-test; display times in local, store in UTC. If the rollup is clean, say so in one line and stop — don't manufacture findings.
Goal: in <10 seconds tell the user what is broken — at the menu level, not the cause level.
Two modes
Mode A — Sweep. No target, or the user asks "what's broken now", "scan plays", "any plays needing attention", "show me problem sessions". Use the v2 plays endpoint to surface the most-attention-worthy plays across the recent window, then suggest a single drill-in.
Mode B — Single-player. The user names a player (UUID prefix, label, device, IP, UA substring) — drill into that one player's live state + recent events.
Pick mode by whether you have a resolvable target. If the user said "triage" alone with no target → Mode A. If they named a target → Mode B (but you may use Mode A's plays scan as supporting context if the player has multiple recent plays).
Mode A — Sweep recent plays
A1. Pull the plays list
harness --insecure --json query plays \
--from $(date -u -v-6H '+%Y-%m-%dT%H:%M:%SZ') \
--limit 200 2>/dev/null \
| jq '.items' > /tmp/plays.json
echo "rows: $(jq length /tmp/plays.json)"
Each item is a PlaySummary (see api/openapi/v2/forwarder.yaml). Trouble signals live in these fields:
| field | meaning | how to read |
|---|
classification | tiered retention class | favourite = operator-starred; interesting = system-flagged; other = normal |
stalls | buffer-empty events | >0 ⇒ user-visible freeze; ≥3 ⇒ painful |
frozen_count | renderer hung (≠ stall) | always notable |
restart_count | mid-play player recovery | >0 ⇒ something was bad enough to restart |
error_event_count | explicit player_error | always notable |
user_marked_count | operator pressed 911 | always notable |
segment_stall_count | stall waiting on segment fetch | >0 = network-correlated stall |
all_failures / transport_failures | failure-tier counters | non-zero = real failures, not retries |
master_manifest_failures / manifest_failures / segment_failures | per-resource fail counts | indicates which HLS layer broke |
dropped_frames | renderer drops | >100 = visible; >1000 = serious |
net_errors / net_faults | network plane errors | from network_requests table join |
bitrate_shifts / resolution_changes | ABR churn | very high = unstable variant boundary |
avg_quality_pct / min_quality_pct | quality envelope | low avg = sustained downshifting |
last_player_error | terminal error string | non-empty = play ended in error |
A2. Score each play
Sum the "user-visible badness" signals with sensible weights. The dashboard's "interesting" filter is (user_marked OR frozen OR error_event OR segment_stall OR restart) > 0; mirror that but rank-order by magnitude.
jq -r '.[] | {
play_id, player_id, started_at, last_seen_at,
classification, last_state, last_player_error,
stalls: (.stalls|tonumber? // 0),
frozen: (.frozen_count|tonumber? // 0),
user_marked: (.user_marked_count|tonumber? // 0),
errors: (.error_event_count|tonumber? // 0),
restarts: (.restart_count|tonumber? // 0),
seg_stalls: (.segment_stall_count|tonumber? // 0),
all_failures: (.all_failures|tonumber? // 0),
transport_failures: (.transport_failures|tonumber? // 0),
manifest_failures: (.manifest_failures|tonumber? // 0),
segment_failures: (.segment_failures|tonumber? // 0),
drops: (.dropped_frames|tonumber? // 0),
net_errors: (.net_errors|tonumber? // 0),
net_faults: (.net_faults|tonumber? // 0),
shifts: (.bitrate_shifts|tonumber? // 0),
avg_q: .avg_quality_pct,
score: (
(.user_marked_count|tonumber? // 0) * 100 # operator 911 — biggest weight
+ (.frozen_count|tonumber? // 0) * 50
+ (.error_event_count|tonumber? // 0) * 40
+ (.restart_count|tonumber? // 0) * 20
+ (.segment_stall_count|tonumber? // 0) * 15
+ (.stalls|tonumber? // 0) * 10
+ (.all_failures|tonumber? // 0) * 5
+ (.transport_failures|tonumber? // 0) * 3
+ ((.dropped_frames|tonumber? // 0) / 100)
+ ((.net_errors|tonumber? // 0) * 2)
+ ((.net_faults|tonumber? // 0) * 3)
)
}' /tmp/plays.json \
| jq -s 'sort_by(-.score) | .[0:8]' > /tmp/plays-ranked.json
(The weights are heuristic — operator-marked events trump everything, frozen frames > errors > restarts > stalls. Tune if your scenario emphasises different signals; the rank order matters more than the absolute score.)
A3. Report — top of the heap
14 plays in the last 6h. 5 worth attention:
★ cfcde730 ee091d13 (iPad) 20:55→21:36 (41m) score 1831
5 stalls, 30 min stall-time, 2 restarts, classification=interesting
last_state=playing, no terminal error
→ /triage ee091d13 (drill the player)
2476fd74 ee091d13 (iPad) 17:25→20:23 (3h) score 765
11 stalls, 10 min stall-time, 1 restart, 583 bitrate shifts
→ ABR thrash candidate — /forensics ee091d13
f9565db5 97282446 (AVPlayer/iOS) 17:34→18:13 (39m) score 612
197 stalls(!), 9082 dropped frames, 18 error events
last_player_error="hls networkError levelLoadError"
→ very bad — /investigate 17:34 or /forensics
1d2f07ea ee091d13 (iPad) 23:27→ongoing score 215
5 stalls (last 36s), 1 frozen frame, audio-rendition 5xx storm
→ /triage ee091d13 (in-flight; check again in 5 min)
21637fda ee091d13 (iPad) 20:41→20:49 (8m) score 142
11 stalls in 8 minutes, restart at end
8–15 lines. Lead with count + favourites-or-stars (★ for classification=favourite). For each: player short-id, device/UA, time window, score, the 2-3 numbers that drive the score, and a one-line next-step skill suggestion. Don't list more than the top 5-8.
If everything is clean ("no stalls, no errors, all classification=other"), say so in one line and stop.
A4. Suggest exactly one next-step
The user wants a single click forward, not a menu. Pick the worst play and recommend either /triage <player_id> (Mode B) or /forensics … if the pattern is repeating across plays for the same player.
Mode B — Single-player triage
Always do these four steps in order. Stop at step 4 — drilling deeper is investigate's job.
1. Resolve + sanity check
harness --insecure players show <target> 2>&1 | head -40
Look at: id, last_seen_at, current_play.id, user_agent, player_metrics.player_state, player_metrics.last_event, player_metrics.player_error, fault_counters.*.
If last_seen_at is more than 60 seconds old, the player has disconnected — say so, suggest checking harness players list for a live one, and stop.
1b. Pull recent plays for this player (multi-play context)
The live players show only sees the current play. To know whether the player has been stable across the last few hours or thrashing through many plays, ask the v2 plays endpoint:
harness --insecure --json query plays \
--player-id "$PID" \
--from $(date -u -v-6H '+%Y-%m-%dT%H:%M:%SZ') \
--limit 50 2>/dev/null \
| jq '.items[0:12] |
map({play_id, started_at, stalls, restart_count, frozen_count,
error_event_count, classification, last_player_error, bitrate_shifts})' \
> /tmp/player-plays.json
Skim it: how many plays in the window, how many flagged interesting, any with last_player_error. If the current play is the 10th in two hours, that's the headline — not whatever just stalled. If they all share a recurring failure shape (every play has a stall, every play has the same terminal error), call that out and recommend /forensics instead of continuing this triage.
2. Pull recent events
Live SSE — capture ~5 seconds of backfill then bail. The timeout here is what makes this fast; don't use a longer one. The grep+sed extracts the SSE payload; the jq filters to operator-relevant events (drops heartbeats and the meta frame).
timeout 5 harness --insecure --json ts <target> --streams events --bundles events 2>/dev/null \
| jq -c 'select(.type and .priority)' > /tmp/events.jsonl
If the file is empty, the events stream may have failed — check harness info and tell the user (don't silently continue with no data).
3. Bucket + surface
Count by priority and type, then surface the most-interesting events:
echo "=== count by priority (1=critical … 4=low) ==="
jq -r .priority /tmp/events.jsonl | sort | uniq -c
echo "=== count by type ==="
jq -r .type /tmp/events.jsonl | sort | uniq -c | sort -rn | head -10
echo "=== P1 events, chronological ==="
jq -c 'select(.priority==1) | {ts, type, info}' /tmp/events.jsonl | sort
echo "=== P2 events, most-recent first, top 10 ==="
jq -c 'select(.priority==2) | {ts, type, info}' /tmp/events.jsonl | sort -r | head -10
4. Report
Give the user a tight summary in roughly this shape:
ipad (ee091d13) player_state=playing buffer=12.3s last_event=heartbeat no errors
Last 5 min: 22 critical, 47 high, 2554 medium/low.
Worst recent events:
18:29:27 stall 262s ← user-visible 4-minute freeze
18:52:51 stall 91s
18:57:03 stall 84s
18:59:26 stall 104s
Recent ABR churn: 1109 upshifts, 297 downshifts in window — heavy
re-evaluation, suggests the player is hovering near a variant
boundary or repeatedly probing.
Suggested next:
/investigate 18:29:27 — deep-dive the worst single event
/forensics — multi-event "why does this keep happening"
8–15 lines total. State the headline fact first ("player is fine" or
"frequent stalls"). List 3-6 specific events with timestamps. Suggest
one next skill — don't list every option.
What NOT to do here
- Don't pull network or sample data. That's investigate's job and
it's slow. Triage is the menu, not the meal.
- Don't speculate about cause. Surface the symptom, suggest the
next skill. The user (or
investigate) decides what to chase.
- Don't filter out P1 events as noise. Even if "this player
always stalls" is true, the operator wants to see it.
- Don't suggest
harness fault add from triage. Mutation is a
separate skill and a separate decision.
Common pitfalls
- The events SSE keeps streaming live rows after backfill, so without
timeout the loop never returns. Always cap with timeout.
harness ts --insecure is required on test-dev (self-signed cert).
If the user has HARNESS_INSECURE=1 exported it works without; if
not, the --insecure flag is needed every time.- The "5 minutes" framing assumes the player's been active that long.
If
last_seen_at is younger, just say "last N minutes since
player came online" — don't pretend you have 5 min of data.
The v2 plays endpoint, in one line
/api/v2/plays returns one row per archived playback with the trouble-signal fields the dashboard uses for its "interesting" filter. CLI: harness --insecure --json query plays [--from ISO] [--player-id UUID] [--play-id UUID] [--classification interesting|other|favourite] [--limit N]. Single-play detail: harness --insecure --json query play <play_id>. Spec: api/openapi/v2/forwarder.yaml § /api/v2/plays.
See also
investigate — drill into a single event with windowed contextforensics — multi-event causal analysis via subagentfinding — capture what triage + investigate taught you
