finding-replay-for-issue

★ 59

When a user says "show me a replay for this error" or "find a recording for issue X", the goal isn't just any linked session — it's the one that best shows what led to the error. Popular issues can have hundreds of linked sessions, and most are crash-only fragments or duplicate occurrences. This skill picks the most useful one.

🔥🔥🔥✓ VerifiedFreeQuick setup

#automation #analytics #git

🧩 One of 7 skills in the posthog/ai-plugin package — works on its own, and pairs well with its siblings.

This is the playbook your agent receives when the skill activates — you don't need to read it to use the skill, but it's here to audit before installing.

by posthog

Finding the best replay for an error tracking issue

Available tools

Tool Purpose posthog:query-error-tracking-issue Get issue details (fingerprint, status, volume) posthog:execute-sql Query exception events to find linked sessions posthog:query-session-recordings-list Fetch recording metadata for candidate sessions posthog:session-recording-get Get full details for the selected recording posthog:vision-observations-list Check for an existing Replay Vision AI summary posthog:vision-scanners-list Find summarizer scanners (scanner_type=summarizer) posthog:vision-scanners-scan-session Run a summarizer scanner on the recording (optional, slow)

Workflow

Step 1 — Get the issue details

Fetch the error tracking issue to understand what you're looking for:

posthog:query-error-tracking-issue
{
 "issueId": " "
}

Note the issue's fingerprint, name, and description — you'll need the fingerprint to find linked sessions.

Step 2 — Find sessions with this error

Query exception events to get session IDs where this error occurred. Order by recency and include basic context:

posthog:execute-sql
SELECT
 $session_id AS session_id,
 count() AS occurrences,
 min(timestamp) AS first_seen,
 max(timestamp) AS last_seen,
 any(properties.$current_url) AS url
FROM events
WHERE event = '$exception'
 AND properties.$exception_fingerprint = ' '
 AND $session_id IS NOT NULL
 AND timestamp > now() - INTERVAL 30 DAY
GROUP BY session_id
ORDER BY last_seen DESC
LIMIT 20

This gives you up to 20 candidate sessions. More candidates means better selection.

Step 3 — Rank the candidates

Fetch recording metadata for the candidate sessions to rank them:

posthog:query-session-recordings-list
{
 "session_ids": [" ", " ", " ", ...],
 "date_from": "-30d"
}

Pick the best recording by filtering out bad candidates, then ranking what's left:

Filter out:

Sessions under 10 seconds (crash-only fragments, no pre-error context)
Sessions over 1 hour (too much data to load, error is a needle in a haystack)

Rank by:

Sweet-spot duration — 2-15 minutes is ideal. Long enough to show the user's journey before the error, short enough to be practical to watch or summarize.
Active time ratio — compare active_seconds to recording_duration. A 20-minute recording with 10 seconds of activity is mostly idle tabs — the user walked away. Prefer sessions where active_seconds / recording_duration is above 0.3 (30%).
Activity score — higher activity_score means the user was actively interacting, not idle. More interesting to watch.
Recency — more recent sessions reflect current app behavior.

Step 4 — Present the finding

Fetch full details for the selected recording:

posthog:session-recording-get
{
 "id": " "
}

Present to the user:

The recording with a link to watch it
Why this one — briefly explain the selection ("longest session with the error, user was browsing 3 pages before hitting it")
Pre-error context — what pages the user visited and key actions before the exception, derived from the events query in step 2 (the url and first_seen columns)
Error frequency — how many times the error occurred in this session

Optional: AI summary via Replay Vision

If the user wants a narrative summary without watching, use Replay Vision — "check-then-scan", since a scanner can only observe a given session once.

Check for an existing summary on the selected recording:

posthog:vision-observations-list
{
 "session_id": " "
}

If an observation has scanner_snapshot.scanner_type summarizer and status succeeded, read scanner_result.model_output (title, summary, intent, outcome, friction_points, keywords) — done.

Find a summarizer scanner if none exists:

posthog:vision-scanners-list
{
 "scanner_type": "summarizer"
}

One → use it. More than one → ask the user which (show name + prompt). None → offer to create one via the creating-replay-vision-scanners skill.

Scan the recording with the chosen scanner (async, several minutes):

posthog:vision-scanners-scan-session
{
 "id": " ",
 "session_id": " "
}

Retrieve by polling vision-observations-list until succeeded.

Tips

If all candidate sessions are very short (<10 seconds), the error likely crashes the page immediately. Note this — it's useful context even without a long replay.
When the issue has very few linked sessions (<3), skip the ranking and just present what's available with a note about the small sample.
If $session_id is null on many exception events, session replay may not be enabled for the affected users. Mention this as a possible gap.
Replay Vision has no per-call focus parameter — a summarizer scanner's focus comes from its own prompt. For error-focused summaries, prefer (or create) a summarizer scanner whose prompt targets error/exception context rather than the whole session.