Finding Replay For Issue

1---
2name: finding-replay-for-issue
3description: >
4  Finds the most informative session recording linked to an error tracking issue.
5  Use when a user has an error tracking issue ID and wants to watch a replay showing
6  what the user was doing when the error occurred. Ranks linked sessions by recency,
7  activity score, and journey completeness, then summarizes the pre-error context.
8  Replaces blind session picking from potentially hundreds of linked recordings.
9---
10 
11# Finding the best replay for an error tracking issue
12 
13When a user says "show me a replay for this error" or "find a recording for issue X",
14the goal isn't just any linked session — it's the one that best shows what led to the error.
15Popular issues can have hundreds of linked sessions, and most are crash-only fragments
16or duplicate occurrences. This skill picks the most useful one.
17 
18## Available tools
19 
20| Tool                                    | Purpose                                                    |
21| --------------------------------------- | ---------------------------------------------------------- |
22| `posthog:query-error-tracking-issue`    | Get issue details (fingerprint, status, volume)            |
23| `posthog:execute-sql`                   | Query exception events to find linked sessions             |
24| `posthog:query-session-recordings-list` | Fetch recording metadata for candidate sessions            |
25| `posthog:session-recording-get`         | Get full details for the selected recording                |
26| `posthog:vision-observations-list`      | Check for an existing Replay Vision AI summary             |
27| `posthog:vision-scanners-list`          | Find summarizer scanners (`scanner_type=summarizer`)       |
28| `posthog:vision-scanners-scan-session`  | Run a summarizer scanner on the recording (optional, slow) |
29 
30## Workflow
31 
32### Step 1 — Get the issue details
33 
34Fetch the error tracking issue to understand what you're looking for:
35 
36```json
37posthog:query-error-tracking-issue
38{
39  "issueId": "<issue_id>"
40}
41```
42 
43Note the issue's `fingerprint`, `name`, and `description` — you'll need the fingerprint
44to find linked sessions.
45 
46### Step 2 — Find sessions with this error
47 
48Query exception events to get session IDs where this error occurred.
49Order by recency and include basic context:
50 
51```sql
52posthog:execute-sql
53SELECT
54    $session_id AS session_id,
55    count() AS occurrences,
56    min(timestamp) AS first_seen,
57    max(timestamp) AS last_seen,
58    any(properties.$current_url) AS url
59FROM events
60WHERE event = '$exception'
61    AND properties.$exception_fingerprint = '<fingerprint>'
62    AND $session_id IS NOT NULL
63    AND timestamp > now() - INTERVAL 30 DAY
64GROUP BY session_id
65ORDER BY last_seen DESC
66LIMIT 20
67```
68 
69This gives you up to 20 candidate sessions. More candidates means better selection.
70 
71### Step 3 — Rank the candidates
72 
73Fetch recording metadata for the candidate sessions to rank them:
74 
75```json
76posthog:query-session-recordings-list
77{
78  "session_ids": ["<id1>", "<id2>", "<id3>", ...],
79  "date_from": "-30d"
80}
81```
82 
83Pick the best recording by filtering out bad candidates, then ranking what's left:
84 
85**Filter out:**
86 
87- Sessions under 10 seconds (crash-only fragments, no pre-error context)
88- Sessions over 1 hour (too much data to load, error is a needle in a haystack)
89 
90**Rank by:**
91 
921. **Sweet-spot duration** — 2-15 minutes is ideal. Long enough to show the user's
93   journey before the error, short enough to be practical to watch or summarize.
942. **Active time ratio** — compare `active_seconds` to `recording_duration`. A 20-minute
95   recording with 10 seconds of activity is mostly idle tabs — the user walked away.
96   Prefer sessions where `active_seconds / recording_duration` is above 0.3 (30%).
973. **Activity score** — higher `activity_score` means the user was actively interacting,
98   not idle. More interesting to watch.
994. **Recency** — more recent sessions reflect current app behavior.
100 
101### Step 4 — Present the finding
102 
103Fetch full details for the selected recording:
104 
105```json
106posthog:session-recording-get
107{
108  "id": "<best_recording_id>"
109}
110```
111 
112Present to the user:
113 
114- **The recording** with a link to watch it
115- **Why this one** — briefly explain the selection ("longest session with the error,
116  user was browsing 3 pages before hitting it")
117- **Pre-error context** — what pages the user visited and key actions before the exception,
118  derived from the events query in step 2 (the `url` and `first_seen` columns)
119- **Error frequency** — how many times the error occurred in this session
120 
121### Optional: AI summary via Replay Vision
122 
123If the user wants a narrative summary without watching, use Replay Vision —
124"check-then-scan", since a scanner can only observe a given session once.
125 
1261. **Check for an existing summary** on the selected recording:
127 
128   ```json
129   posthog:vision-observations-list
130   {
131     "session_id": "<best_recording_id>"
132   }
133   ```
134 
135   If an observation has `scanner_snapshot.scanner_type` `summarizer` and
136   `status` `succeeded`, read `scanner_result.model_output` (`title`, `summary`,
137   `intent`, `outcome`, `friction_points`, `keywords`) — done.
138 
1392. **Find a summarizer scanner** if none exists:
140 
141   ```json
142   posthog:vision-scanners-list
143   {
144     "scanner_type": "summarizer"
145   }
146   ```
147 
148   One → use it. More than one → ask the user which (show name + prompt). None →
149   offer to create one via the `creating-replay-vision-scanners` skill.
150 
1513. **Scan the recording** with the chosen scanner (async, several minutes):
152 
153   ```json
154   posthog:vision-scanners-scan-session
155   {
156     "id": "<scanner_id>",
157     "session_id": "<best_recording_id>"
158   }
159   ```
160 
1614. **Retrieve** by polling `vision-observations-list` until `succeeded`.
162 
163## Tips
164 
165- If all candidate sessions are very short (<10 seconds), the error likely crashes
166  the page immediately. Note this — it's useful context even without a long replay.
167- When the issue has very few linked sessions (<3), skip the ranking and just present
168  what's available with a note about the small sample.
169- If `$session_id` is null on many exception events, session replay may not be enabled
170  for the affected users. Mention this as a possible gap.
171- Replay Vision has no per-call focus parameter — a summarizer scanner's focus
172  comes from its own prompt. For error-focused summaries, prefer (or create) a
173  summarizer scanner whose prompt targets error/exception context rather than the
174  whole session.
175