posthog/skills

finding-replay-for-issue

Finds the most informative session recording linked to an error tracking issue.

View source

How to use

  1. Copy the installation command and review the source package before installing it in your own agent environment.
  2. Check the source document for required tools, credentials and supported hosts.
  3. Describe your input and desired deliverable; review the output against the source material.
npx skills add https://github.com/posthog/skills --skill finding-replay-for-issue

Before you start

  • Installation does not include a model subscription, API allowance or permission to access your files.
  • Repository stars and installation counts describe activity, not an independent quality or security test.
Original skill document

Rendered from the source repository. Headings, examples, code, tables, links, and referenced images are preserved.

Finding the best replay for an error tracking issue

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.

Available tools

ToolPurpose
posthog:query-error-tracking-issueGet issue details (fingerprint, status, volume)
posthog:execute-sqlQuery exception events to find linked sessions
posthog:query-session-recordings-listFetch recording metadata for candidate sessions
posthog:session-recording-getGet full details for the selected recording
posthog:vision-observations-listCheck for an existing Replay Vision AI summary
posthog:vision-scanners-listFind summarizer scanners (scanner_type=summarizer)
posthog:vision-scanners-scan-sessionRun 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:

json
posthog:query-error-tracking-issue
{
  "issueId": "<issue_id>"
}

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:

sql
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 = '<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:

json
posthog:query-session-recordings-list
{
  "session_ids": ["<id1>", "<id2>", "<id3>", ...],
  "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:

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

  1. 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%).

  1. Activity score — higher activity_score means the user was actively interacting,

not idle. More interesting to watch.

  1. Recency — more recent sessions reflect current app behavior.

Step 4 — Present the finding

Fetch full details for the selected recording:

json
posthog:session-recording-get
{
  "id": "<best_recording_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.

  1. Check for an existing summary on the selected recording:
json
   posthog:vision-observations-list
   {
     "session_id": "<best_recording_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.

  1. Find a summarizer scanner if none exists:
json
   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.

  1. Scan the recording with the chosen scanner (async, several minutes):
json
   posthog:vision-scanners-scan-session
   {
     "id": "<scanner_id>",
     "session_id": "<best_recording_id>"
   }
  1. 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.

Related skills

  • `investigating-error-issue` — the quantitative side: volume, breakdowns, and stack traces for the same issue
  • `investigating-replay` — deep-dive one of the linked sessions
  • `diagnosing-missing-recordings` — when exception events have no $session_id or the linked recordings are gone

Related by task

from this repository

More skills

All skills
posthog
Official

instrument-llm-analytics

Add PostHog AI Observability to trace AI model usage. Use after implementing LLM features or reviewing PRs to ensure all generations are captured with token counts, latency, and costs. Also handles initial PostHog SDK setup if not yet installed.

1h installs
1
GitHub stars
80
Updated
Nov 20
posthog
Official

exploring-live-traffic

Inspects PostHog Web analytics Live tab data — current users online, last-30-minutes pageviews, top pages, referrers, devices, browsers, countries, bot traffic, and the per-minute bot/users charts. Use when the user asks "who is on my site right now?", "what is happening live?", "what bots are crawling me?", asks about the "live tab" / "live dashboard", wants live numbers (last 30 min), or wants help filtering or drilling into the live view. Also covers building product-analytics insights that m

1h installs
1
GitHub stars
79
Updated
Nov 11
posthog
Official

instrument-feature-flags

Add PostHog feature flags to gate new functionality. Use after implementing features or reviewing PRs to ensure safe rollouts with feature flag controls. Also handles initial PostHog SDK setup if not yet installed.

1h installs
1
GitHub stars
79
Updated
Nov 11
posthog
Official

querying-posthog-data

Explains how to query PostHog data, defaulting to typed runners for supported product analytics. Read it before you write HogQL/SQL. Also read it before you call execute-sql against PostHog. Use it to find or aggregate PostHog entities. These entities include insights, dashboards, cohorts, feature flags, experiments, surveys, hog flows, warehouse data, and persons. Use it for trends, funnels, retention, lifecycle, paths, stickiness, web analytics, error tracking, logs, sessions, and LLM traces.

1h installs
1
GitHub stars
79
Updated
Nov 11