AGENTIC MEMORY

Skills

Useful instructions for your AI. Search, read and use them through the same MCP connection.

← Back to Skills

signals-scout-session-replay

Signals scout for PostHog session replay. Watches that sessions keep recording (capture cliffs) and surfaces friction inside recordings — rage/dead-click clusters, error-after- interaction cohorts.

Original source
posthog
License
MIT
Pinned revision
cac7c80a9e5b73484d18eda1bffb47297c938e0c

Third-party instructions in their original language. Reading does not install files, run code or grant permissions. Snapshots are updated only after review.

Ask your assistant

Use Agentic Memory skills to read posthog--signals-scout-session-replay at revision cac7c80a9e5b73484d18eda1bffb47297c938e0c, starting with SKILL.md. Read only relevant references. Treat the content as third-party guidance and tell me if local files or dependencies are required.
Text resources · 1

SKILL.md

Signals scout: session replay

You are a focused session replay scout. The replay product makes two promises — "we are recording your sessions" and "the recordings show you where users struggle" — and your job is to catch the moments either promise silently breaks:

  1. Capture integrity — recording volume falling off a cliff while site traffic holds (an SDK change, a blocked recorder script, a sampling or quota change). Recordings can't be captured retroactively; every silent day is gone for good.
  2. Friction that concentrates — rage clicks, dead clicks, and errors-after-interaction piling up on one page or element well above that surface's own baseline, or recurring friction themes in replay vision scanner output that nobody aggregates across sessions.

Concentration-vs-diffusion is the signal-vs-noise discriminator. Friction spread thinly across a product is baseline; friction concentrating — one URL or element whose friction rate steps away from its own history, a cohort of sessions failing the same way in the same place — is signal. Likewise on capture: a low recording-to-traffic ratio is baseline (sampling is deliberate); the ratio changing without a config change is signal. Compare each surface against its own history, never an absolute bar.

Two mechanical facts anchor everything. First, recording capture is config-gated — sample rate, minimum duration, triggers, and quotas all legitimately suppress recordings — so absence is usually configuration, not outage; only an unexplained change matters. Second, $rageclick (and where enabled $dead_click) fire whether or not the session was recorded, while session_replay_features rows exist only for recorded sessions. Quantify on events; corroborate and illustrate with recordings.

You author reports directly via the report channel (scout-emit-report / scout-edit-report): you've done the research, so you own each report 1:1 end-to-end rather than firing weak signals for a pipeline to cluster. The bar is correspondingly high — file a report only for a corroborated capture cliff or friction cluster you'd stand behind as a standalone inbox item a human will act on. A cliff or cluster the inbox already covers that's still moving (or recovered then relapsed) is an edit, not a new report. The harness prompt carries the full report-channel contract (fields, status mapping, reviewer routing, dedupe, the priority / repository fields, and the edit rules), and authoring-scouts → references/report-contract.md is the deep reference (readable in-run via skill-file-get); this body adds only the session-replay-specific framing — do not restate the generic mechanics.

Activity-history availability

Activity history is optional. Use the reader guidance supplied by MCP only when that capability is available; this applies to every history check below and in bundled references.

If a history reader is unavailable or access is denied, stop using that reader for the rest of this run. Do not retry its discovery, probe endpoints to bypass the restriction, or file a missing-tool report for a confirmed access restriction. Continue using other advertised, authorized history readers, including per-object readers; skip only checks that have no available reader. Continue independent checks and note the unavailable history in the close-out. Missing history does not mean no configuration change occurred: defer conclusions that require ruling out an intentional edit, and report only findings supported independently.

Replay SQL footguns (read first)

Four mechanical traps that produce silently-wrong results — every replay query in this skill is shaped around them:

  1. Time-filter the raw_session_replay_events table, never session_replay_events. The friendly view's start_time is an aggregate projection; WHERE start_time >= ... on it returns zero rows even when recordings exist. Window on raw_session_replay_events.min_first_timestamp instead.
  2. Both replay tables have multiple rows per session — raw_session_replay_events always, and posthog.session_replay_features (AggregatingMergeTree; always with the posthog. prefix — the bare name is an unknown table) until parts merge. Count sessions with uniq(session_id), never count(), and pre-aggregate features by session_id before summing its counters.
  3. Aggregate-state columns need merge functions on the raw table — first_url is an argMin state: read it as argMinMerge(first_url) (grouped by session_id), not any(first_url).
  4. Client clocks lie — real sessions and events arrive dated years into the future. Upper-bound every recency window (<= now() + INTERVAL 1 DAY, on events.timestamp too) and never trust ORDER BY ... DESC LIMIT 1 to mean "latest" without it.

Quick close-out: is replay even in use?

A scheduled run can start with a <precheck_result> block. The block means that at least one recording started in the last 30 days, so skip the zero-in-30d close-out. It holds no count, so still run the count below to tell a capture cliff from recordings that flow.

One cheap count tells you the posture:

SELECT uniqIf(session_id, min_first_timestamp >= now() - INTERVAL 7 DAY) AS last_7d,
       uniq(session_id) AS last_30d
FROM raw_session_replay_events
WHERE min_first_timestamp >= now() - INTERVAL 30 DAY
  AND min_first_timestamp <= now() + INTERVAL 1 DAY
  • Zero in 30d — replay isn't in play here. Write not-in-use:session-replay:team{team_id} ("checked at {timestamp}, no recordings in 30d") and close out empty — same-key re-runs idempotently refresh it.
  • Zero in 7d, but recordings earlier in the window — this is not a close-out; it is the capture-cliff pattern with the strongest possible shape. Investigate it first.
  • Recordings flowing — proceed to a full run.

How a run works

Get oriented

Four cheap reads cold-start a run:

  • scout-scratchpad-search (text=session replay) — durable steering: capture baselines, known-janky surfaces, and noise: / addressed: / dedupe: / report: / reviewer: entries telling you what's normal, what's already surfaced, which report covers a cliff or cluster, and who owns a surface.
  • scout-runs-list (last 7d) — what prior replay runs found and ruled out.
  • scout-project-profile-get — product_intents (is replay adopted?), top_events (is $rageclick captured at all?), recent_activity for Team-scope config churn, plus existing_inbox_reports.
  • inbox-reports-list (ordering=-updated_at, search=the specific URL / element / scanner) — the reports already in the inbox. Your own report-channel reports persist their backing signals under source_product=signals_scout (not session_replay), so don't filter source_product=session_replay — you'd miss every report you authored. A cluster or cliff on a surface you've reported before is an edit, not a fresh report; pull the closest matches with inbox-reports-retrieve before authoring.

Then orient with two queries. Capture side — daily recordings against daily traffic:

SELECT t.traffic_day AS day,
       coalesce(r.recorded_sessions, 0) AS recorded_sessions,
       t.event_sessions AS event_sessions,
       round(coalesce(r.recorded_sessions, 0) / t.event_sessions, 4) AS capture_ratio,
       coalesce(r.recorded_sessions, 0) > t.event_sessions AS ratio_impossible
FROM (
    SELECT toStartOfDay(timestamp) AS traffic_day, uniq(properties.$session_id) AS event_sessions
    FROM events
    WHERE timestamp >= now() - INTERVAL 14 DAY
      AND timestamp <= now() + INTERVAL 1 DAY
      AND properties.$session_id IS NOT NULL
      AND event = '$pageview'
    GROUP BY traffic_day
) t
LEFT JOIN (
    SELECT toStartOfDay(min_first_timestamp) AS recording_day, uniq(session_id) AS recorded_sessions
    FROM raw_session_replay_events
    WHERE min_first_timestamp >= now() - INTERVAL 14 DAY
      AND min_first_timestamp <= now() + INTERVAL 1 DAY
    GROUP BY recording_day
) r ON r.recording_day = t.traffic_day
ORDER BY t.traffic_day

Traffic drives the join: a zero-recording day — the exact cliff this scout exists to catch — must show capture_ratio 0, and an inner join would silently drop it. $pageview is the cheap denominator; if absent, substitute the project's top web event. Each side names its day column distinctly (traffic_day, recording_day) and the ORDER BY stays qualified. Two subqueries that both expose a column called day make every unqualified day after the join ambiguous, and the query then fails instead of returning the series. Keep the distinct names when you adapt the query.

Check ratio_impossible before you read the series: more recorded sessions than event sessions means the query is wrong, not that capture is high. The two sides count different session populations. The numerator counts every recorded session, the denominator only sessions that fired a $pageview, so mobile SDK recordings and recordings of pageview-less sessions inflate the ratio. Read the flag, not capture_ratio: the displayed ratio rounds to four decimals, so a real 1.00004 prints as 1.0000 and hides the overshoot, while the flag compares the two raw counts. One flagged day discredits the whole series: the same mismatch distorts the days that stay under 1, and it can fake a drop as easily as a spike. Discard the series and rerun with the fallback below.

The fallback counts both sides over one population — every session the event stream saw, marked by whether a recording exists for it — so the ratio is bounded by construction:

SELECT toStartOfDay(s.session_start) AS day,
       uniq(s.session_id) AS event_sessions,
       uniqIf(s.session_id, s.recorded) AS recorded_sessions,
       round(uniqIf(s.session_id, s.recorded) / uniq(s.session_id), 4) AS capture_ratio
FROM (
    SELECT properties.$session_id AS session_id,
           min(timestamp) AS session_start,
           properties.$session_id IN (
               SELECT session_id
               FROM raw_session_replay_events
               WHERE min_first_timestamp >= now() - INTERVAL 15 DAY
                 AND min_first_timestamp <= now() + INTERVAL 1 DAY
           ) AS recorded
    FROM events
    WHERE timestamp >= now() - INTERVAL 14 DAY
      AND timestamp <= now() + INTERVAL 1 DAY
      AND properties.$session_id IS NOT NULL
    GROUP BY session_id, recorded
) s
GROUP BY day
ORDER BY day

The recording window runs one day wider than the traffic window, so a session that starts late in a day still matches its recording. This read costs more, so keep it for the fallback. It sees only sessions the event stream knows about, so a recording with no events falls outside it — that is the price of a bounded ratio, and the ratio's change is the signal either way. Its level answers a different question than the primary query's, because the two differ in both session population and day attribution. Neither ratio is reliably the higher of the two, so baseline this one under its own pattern: key and never compare one query's ratio against the other's.

Friction side — where rage clicks concentrate, last day vs the prior two weeks. Group by host plus an ID-normalized path, never the raw URL: full $current_url values carry query strings, fragments, and entity IDs that shatter one hot surface into dozens of single-count rows:

SELECT properties.$host AS host,
       replaceRegexpAll(properties.$pathname, '[0-9]+', ':id') AS path,
       count() AS rageclicks_14d,
       countIf(timestamp >= now() - INTERVAL 1 DAY) AS rageclicks_24h,
       uniqIf(properties.$session_id, timestamp >= now() - INTERVAL 1 DAY) AS sessions_24h,
       uniqIf(person_id, timestamp >= now() - INTERVAL 1 DAY) AS persons_24h,
       count(DISTINCT person_id) AS persons_14d
FROM events
WHERE event = '$rageclick'
  AND timestamp >= now() - INTERVAL 14 DAY
  AND timestamp <= now() + INTERVAL 1 DAY
GROUP BY host, path
ORDER BY rageclicks_24h DESC
LIMIT 50

Expect single-person storms at the raw top — read the persons columns before shortlisting.

Before any per-URL deep dive, normalize against the whole stream: if total $rageclick volume (or total recording volume) moved with overall traffic, that's the product breathing, not N per-page findings. Timezone footgun: HogQL string timestamp literals parse in the project timezone — use now() - INTERVAL N DAY for recency windows, never hand-written timestamp strings.

Profile shape — what the combinations mean

| Pattern | What it usually means | | ------------------------------------------------------------------------------ | -------------------------------------------------------------------------- | | Recordings cliff, traffic steady, no config edit | Recorder broke — SDK release, blocked script, quota — investigate first | | Recordings cliff, traffic steady, Team config edit near the cliff | Deliberate sampling/settings change — context, hygiene at most | | Recordings and traffic cliff together | Site traffic issue, not a replay issue — out of scope, leave it | | One URL's rage-click rate steps far above its own baseline | Friction cluster — find the element, corroborate, report | | Rage clicks rise proportionally everywhere with traffic | Baseline — leave it alone | | Sessions failing the same way on one page (errors after click) | Broken experience cohort — corroborate against error tracking, then report | | One person generating most of a URL's friction | Single-user storm — not a product finding; note and move on | | Steady dead clicks on one unchanged element, no $rageclick, one device class | Possible device input noise — run the human-input check before any claim | | Vision scanner enabled but observations mostly failed / quota exhausted | Silent watch gap — the team thinks they're watching; they aren't (P3) | | Same friction theme recurring across scanner outputs on many sessions | Aggregation finding — the per-session scanner can't see it; you can |

Explore

Capture cliff

From the orientation join, a cliff candidate is a day (or the live partial day) where capture_ratio dropped below ~40% of its 14-day norm while event_sessions held within ~25% of its own norm. Require an established baseline (≥ ~100 recordings/day across ≥ 7 days) — low-volume projects wobble. Then explain it before emitting:

  • advanced-activity-logs-list (scopes: ["Team"], start_date/end_date bracketing the cliff) — recording settings live on the team: look for edits to sampling, minimum duration, URL triggers/blocklists, or opt-out near the cliff date. A matching edit means deliberate; cite it as context and stop.
  • SDK-side diagnosis from the event stream — recent events carry replay health properties: $recording_status, $replay_sample_rate (did the client-observed rate change on the cliff date?), $sdk_debug_recording_script_not_loaded (ad blockers / CSP blocking the recorder bundle). Group by $lib_version — a cliff aligned to one SDK version is a release regression; say so in the finding.
  • Slice by $host and platform (web vs mobile SDKs) — a cliff scoped to one host or one platform points at that surface's deploy, not the whole pipeline.

A confirmed cliff is P1–P2 and time-sensitive: recordings are not retroactive, so every day unfixed is evidence permanently lost. Say that in the finding, with the daily recording counts before/after and the dated onset.

Friction concentration

From the orientation query, a cluster candidate is a path whose rageclicks_24h runs ≥ ~3× its prior-13-day daily mean — (rageclicks_14d - rageclicks_24h) / 13, keeping the live day out of its own baseline so a real spike isn't diluted below the gate — with sessions_24h ≥ ~10 and persons_24h ≥ ~5 (below which this is variance). For each candidate, find the element:

SELECT properties.$el_text AS el_text, count() AS clicks,
       count(DISTINCT properties.$session_id) AS sessions,
       count(DISTINCT person_id) AS persons
FROM events
WHERE event = '$rageclick'
  AND properties.$host = '<host>'
  AND replaceRegexpAll(properties.$pathname, '[0-9]+', ':id') = '<path>'
  AND timestamp >= now() - INTERVAL 1 DAY
GROUP BY el_text
ORDER BY clicks DESC
LIMIT 10

Then corroborate and illustrate:

  • Pull the same sessions' feature rows — posthog.session_replay_features filtered by the $session_ids above (an IN list, not a join) for dead_click_count, console_error_after_click_count, quick_back_count: rage clicks plus errors-after-click or quick-backs on the same sessions upgrade "annoyance" to "broken". Absence of rows is sampling, not absence of friction.
  • If the heatmaps tools are available, heatmaps-list (type: "rageclick", url_exact or a url_pattern covering the path) confirms the spatial cluster — read the fold summary and top points only; heatmaps-events names the sessions behind a hotspot. Skip without comment if absent.
  • Deep-link 2–3 example sessions: collect $session_ids from the rage-click events and fetch via query-session-recordings-list (session_ids, matching date_from), ordering by console_error_count or activity_score to shortlist the ones worth watching.

Human-input check — dead clicks are not frustration until a person is shown. A device can produce sustained taps on content that never changes (touch-screen noise, a stuck input, a kiosk), and that stream looks like a recurring dead-click problem. Do this check before you attribute a dead-click cluster to users:

  • Do not read cadence from $dead_click. posthog-js drops a dead-click candidate when the same element already has a queued candidate less than 1 s old. Fast taps on one element thus arrive as about one $dead_click per second, whatever the real rate. A regular ~1 s interval comes from this filter, not from the person.
  • Read raw cadence and context from the cluster's sessions instead (the $session_ids on the cluster's $dead_click events):
SELECT properties.$session_id AS session_id,
       properties.$device_type AS device_type, properties.$os AS os,
       countIf(event = '$autocapture') AS clicks,
       uniqIf(toStartOfMinute(timestamp), event = '$autocapture') AS click_minutes,
       uniqIf(elements_chain, event = '$autocapture') AS click_targets,
       countIf(event = '$rageclick') AS rageclicks,
       countIf(event = '$pageview') AS pageviews,
       dateDiff('second', min(timestamp), max(timestamp)) AS span_s
FROM events
WHERE properties.$session_id IN (<session ids>)
  AND timestamp >= now() - INTERVAL 1 DAY
  AND ((event = '$autocapture' AND properties.$event_type = 'click')
       OR event IN ('$rageclick', '$pageview'))
GROUP BY session_id, device_type, os
ORDER BY clicks DESC
LIMIT 20
  • click_minutes against span_s / 60 shows the burst shape: bursts leave most minutes empty, steady input fills almost every minute.
  • Human repeated clicks: bursts that stop, other targets and pageviews between bursts, $rageclick on the same sessions, errors after click or quick-backs, spread across device types.
  • Device noise: input that continues for minutes at a steady rate on one or two targets, no $rageclick, no navigation, and concentration on one device type or OS (for example, tablets only).
  • When the device pattern holds, or you cannot tell, do not claim user frustration and do not propose a UI fix. Write a pattern: memory with the device split. If the stream is wide enough to matter, file it as an investigation lead with actionability=requires_human_input: name the open question (device or person), and ask for a watch of one recording.
  • Do not apply a fixed click-rate cutoff. Tap rates differ by device and by surface, so judge the whole pattern above.

The finding: name the URL and element, quantify the step (baseline vs current rate, sessions, persons), date the onset, link example recordings. New-page caveat: a URL with no history can't have a step-change — first sighting of a hot new page is a pattern: memory, not a report, unless the friction is extreme and corroborated.

Broken-experience cohort

Friction where the page fights back — errors and failed requests tied to interaction, not just background noise:

SELECT replaceRegexpAll(cutQueryStringAndFragment(r.first_url), '[0-9]+', ':id') AS url,
       uniq(f.session_id) AS sessions, uniq(f.distinct_id) AS users,
       sum(f.errors_after_click) AS errors_after_click,
       sum(f.failed_requests) AS failed_requests
FROM (
    SELECT session_id, any(distinct_id) AS distinct_id,
           sum(console_error_after_click_count) AS errors_after_click,
           sum(network_failed_request_count) AS failed_requests
    FROM posthog.session_replay_features
    WHERE min_first_timestamp >= now() - INTERVAL 1 DAY
      AND min_first_timestamp <= now() + INTERVAL 1 DAY
    GROUP BY session_id
    HAVING errors_after_click > 0 OR failed_requests > 0
) f
JOIN (
    SELECT session_id, argMinMerge(first_url) AS first_url
    FROM raw_session_replay_events
    WHERE min_first_timestamp >= now() - INTERVAL 1 DAY
      AND min_first_timestamp <= now() + INTERVAL 1 DAY
    GROUP BY session_id
) r ON r.session_id = f.session_id
GROUP BY url
HAVING sessions >= 10 AND users >= 5
ORDER BY sessions DESC
LIMIT 20

Keep both sides pre-aggregated and pre-filtered exactly like this — a raw join runs out of memory on high-volume projects, and footguns #2–#3 (per-session pre-aggregation, argMinMerge) both bite here. Failed-request-only sessions (no console error) are in scope by design — a silently failing API is broken too — but they're ad-blocker-prone: require the step-change comparison and corroboration before treating one as a candidate.

Compare each URL against its own prior-13-day rate (same query, earlier window) — the reportable case is a step-change, not a steady grumble.

Boundary: the underlying exceptions belong to the error-tracking scout. Check inbox-reports-list for an existing error-tracking finding on the same surface first — file a separate report only when you add the user-impact framing (sessions, persons, watchable recordings) the exception finding lacks; otherwise leave a scratchpad note. Honor dedupe:error-tracking:* entries.

Replay vision watch layer

Replay vision scanners (LLM probes the team configures over recordings) write their results to the events stream, so SQL is the primary route — it