Add client-perf-diagnosis skill

[habdelra]

Background

The client performance telemetry adds an always-on browser instrument that beacons six event types to Loki and a Grafana dashboard, so real client behavior is measurable and attributable to a specific user or session. This adds the operator-facing counterpart: a diagnostic skill that turns a field complaint into a measured investigation against that telemetry.

The motivating shape of the complaint is concrete — "user XYZ said the app was slow loading their card" — and the whole reason attribution is in the pipeline is to answer it. So the skill leads with the user-attributed drill-down: pivot to the account's matrix_user_id, pin the session, find the slow card-load (the "Loading card…" window) and its settle_ms, then spider into the sibling events in that same session that explain the cost.

What the skill covers

A mode per investigation, all sharing the matrix_user_id / session_id drill-down:

• A user reports a slow card load — the hub mode; from the pinned session, spider into slow server round-trips, a main-thread freeze, heavy deserialization, rebuild churn, or index-event churn.
• A browser froze — read the wedge events and their fn @ url:char blocking-frame breadcrumb (source-map-resolvable for minified builds), plus profiler stacks where sampled.
• Slow server round-trips — server-request latency by endpoint, joined to the realm-server's own realm:requests / realm:search-timing stage breakdown via the logging correlation id.
• Heavy deserialization, rebuild churn (grouped by the module that forced it), and realm index-event write-burst churn — framed as the causal upstream that explains why a rebuild fired or a linked card reloaded.

It documents the pipeline, the Loki label-vs-JSON-field split, the six event schemas, the working LogQL for each mode (lifted from the dashboard so they match the instrument), the local-dev bring-up, and the seam to indexing-diagnostics for the server-side half of a request.

Notes

• Stacked on the telemetry instrument + dashboard change; this branch adds only the skill file. Retarget to main once the base merges.
• The verified half — the mechanism, event glossary, dashboard, and query building blocks — is grounded in the local pipeline. The symptom interpretation is written as "how to investigate" with a calibrate-against-the-realm's-baseline caveat rather than fixed thresholds, so it stays honest as real field data accrues.

🤖 Generated with Claude Code

[burieberry]

Code review

Verified the skill's claims against the telemetry implementation on the base branch — the doc is accurate throughout except for two points, both of which would mislead a diagnostician in the direction of a false negative. Neither is a code change; both are fixes to SKILL.md.

1. Mode B's primary "find the wedges" query drops longtask-only freezes

The query filters top_frame_function!="":

... | event_type="wedge" | top_frame_function!="" [$__range]

But #emitWedge emits top_frame_function="" whenever the wedge was corroborated by a longtask with no LoAF script attribution — the fallback path (scripts is only populated from loafInWindow, so topFrame is undefined → top_frame_function ?? ''). The field's own comment says as much: "Empty when no LoAF attribution is available (e.g. the longtask fallback)."

The wedge is still recorded — it passed corroboration precisely because a longtask was present. So on any browser/window where a real freeze produced only a longtask entry, this query returns nothing, and Mode B reports "no freeze" on exactly the symptom it exists to diagnose. Suggest dropping the top_frame_function!="" filter (or grouping with a coalesce/fallback label) so longtask-only wedges still surface — the top_frames breadcrumb and longtask_count are still readable on those lines.

2. The retried="true" sentence mis-describes duration_ms

Line ~133 says a retried server-request "re-attempted the fetch after a transient auth (401) refresh, folding the extra round-trip into duration_ms."

The implementation does the opposite. The timing middleware is innermost, so it times each attempt separately (start = now() … now() - start per attempt). A retried event's duration_ms is the final successful attempt's own duration, and recordServerRequestTiming additionally splices the buffered 401 event out of the ring buffer. So the reauth/401 round-trip is excluded, not folded in. As written, the doc would lead a diagnostician to over-attribute a retried request's duration_ms to network/server latency that actually omits the reauth cost. Suggest rewording to: the reauth round-trip is not included — duration_ms covers only the final attempt, and the transient 401 is dropped from the stream.

---

🤖 Review generated with Claude Code

[habdelra]

[Claude Code 🤖] Both correct — verified against the emit path and fixed:

1. Longtask-only wedges — dropped the top_frame_function!="" filter from Mode B's wedge query. A wedge corroborated only by a longtask (no LoAF attribution) has an empty top_frame_function but is a real freeze, so filtering it hid exactly the symptom the mode exists to find. Those now surface, grouped under the blank frame, with top_frames / longtask_count / blocked_ms readable on the line.
2. retried="true" and duration_ms — reworded. Each attempt is timed separately (innermost middleware) and the transient 401 is spliced out of the stream, so duration_ms is the final successful attempt only and excludes the reauth round-trip; the doc now says so instead of the reverse.