finding-replay-for-issue

エラー追跡の課題に最適なリプレイを見つける

ユーザーが「このエラーのリプレイを見せて」や「課題 X の録画を見つけて」と言った場合、 目的は単にリンクされたセッションを見つけることではなく、エラーに至った経緯を最もよく示すセッションを見つけることです。 人気のある課題には、リンクされたセッションが数百件あることもありますが、その大半はクラッシュ時のみの断片や 重複した発生記録です。このスキルでは、最も役立つものを選びます。

利用可能なツール

ツール	目的
posthog:query-error-tracking-issue	課題の詳細を取得する（フィンガープリント、ステータス、発生数）
posthog:execute-sql	例外イベントをクエリして、関連するセッションを見つける
posthog:query-session-recordings-list	候補セッションの録画メタデータを取得する
posthog:session-recording-get	選択した録画の詳細をすべて取得する
posthog:vision-observations-list	既存の Replay Vision AI 要約を確認する
posthog:vision-scanners-list	要約スキャナー（scanner_type=summarizer）を見つける
posthog:vision-scanners-scan-session	録画に要約スキャナーを実行する（任意、時間がかかります）

ワークフロー

ステップ 1 — 課題の詳細を取得する

エラー追跡の課題を取得し、探しているものを把握します。

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

課題の fingerprint、name、description に注目してください。関連するセッションを見つけるには、フィンガープリントが必要です。

ステップ 2 — このエラーが発生したセッションを見つける

例外イベントをクエリして、このエラーが発生したセッション ID を取得します。 新しい順に並べ、基本的なコンテキストを含めます。

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

これにより、最大 20 件の候補セッションが得られます。候補が多いほど、より適切に選択できます。

ステップ 3 — 候補をランク付けする

候補セッションの録画メタデータを取得し、ランク付けします。

posthog:query-session-recordings-list
{
  "session_ids": ["<id1>", "<id2>", "<id3>", ...],
  "date_from": "-30d"
}

不適切な候補を除外してから、残った候補をランク付けし、最適な録画を選びます。

除外する条件：

• 10 秒未満のセッション（クラッシュ時のみの断片で、エラー発生前のコンテキストがない）
• 1 時間を超えるセッション（読み込むデータが多すぎて、広大な干し草の山から針を探すような状態になる）

ランク付けの基準：

1. 最適な長さ — 2～15 分が理想です。エラー発生前のユーザーの行動を示すには十分な長さがあり、視聴や要約に現実的な範囲に収まります。
2. アクティブ時間の比率 — active_seconds と recording_duration を比較します。20 分の録画でアクティビティが 10 秒しかない場合、ほとんどは操作されていないタブです。ユーザーはその場を離れています。 active_seconds / recording_duration が 0.3（30%）を超えるセッションを優先します。
3. アクティビティスコア — activity_score が高いほど、ユーザーが操作を行っていたことを示します。操作されていないセッションより、視聴する価値があります。
4. 新しさ — 新しいセッションほど、現在のアプリの動作を反映しています。

ステップ 4 — 見つかった内容を提示する

選択した録画の詳細をすべて取得します。

posthog:session-recording-get
{
  "id": "<best_recording_id>"
}

ユーザーには次の内容を提示します。

• 録画 — 視聴リンクを添えます
• 選んだ理由 — なぜこれを選んだのかを簡潔に説明します（「エラーが発生したセッションの中で最も長く、ユーザーはエラーに遭遇する前に 3 ページを閲覧していました」など）
• エラー発生前のコンテキスト — ステップ 2 のイベントクエリから導き出した、ユーザーが訪問したページと主な操作（url 列と first_seen 列を使用）
• エラーの発生頻度 — このセッションでエラーが発生した回数

任意：Replay Vision による AI 要約

ユーザーが視聴せずに説明的な要約を希望する場合は、Replay Vision を使用します。スキャナーは各セッションを一度しか確認できないため、「確認してからスキャン」します。

1. 選択した録画に既存の要約があるか確認します。

   posthog:vision-observations-list
   {
     "session_id": "<best_recording_id>"
   }
   

   観測データに scanner_snapshot.scanner_type が summarizer、status が succeeded のものがあれば、scanner_result.model_output（title、summary、 intent、outcome、friction_points、keywords）を読み取れば完了です。

2. 既存の要約がない場合は、要約スキャナーを探します。

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

   1 つ見つかった場合は、それを使用します。複数見つかった場合は、ユーザーにどれを使うか尋ねます（名前とプロンプトを提示）。見つからない場合は、creating-replay-vision-scanners スキルを使って作成することを提案します。

3. 選択したスキャナーで録画をスキャンします（非同期で数分かかります）。

   posthog:vision-scanners-scan-session
   {
     "id": "<scanner_id>",
     "session_id": "<best_recording_id>"
   }
   

4. vision-observations-list をポーリングし、succeeded になるまで結果を取得します。

ヒント

• 候補となるセッションがすべて非常に短い（10 秒未満）場合は、エラーによってページがすぐにクラッシュしている可能性が高いです。長いリプレイがなくても有用な情報となるため、その旨を記してください。
• 問題に関連付けられたセッションが非常に少ない（3 件未満）場合は、ランキングを省略し、サンプル数が少ないことを注記して利用可能な情報を提示してください。
• 多くの例外イベントで $session_id が null の場合、影響を受けたユーザーに対してセッションリプレイが有効になっていない可能性があります。考えられる不足点として言及してください。
• Replay Vision には呼び出しごとのフォーカス指定パラメーターがありません。要約スキャナーのフォーカスは、スキャナー独自のプロンプトによって決まります。エラーに焦点を当てた要約には、セッション全体ではなく、エラー／例外のコンテキストを対象とするプロンプトを持つ要約スキャナーを優先するか、作成してください。

関連スキル

• investigating-error-issue — 定量的な調査を行います。同じ問題の発生件数、内訳、スタックトレースを確認します
• investigating-replay — 関連セッションの 1 つを詳しく調査します
• diagnosing-missing-recordings — 例外イベントに $session_id がない場合や、関連する録画がなくなっている場合に使用します