mcpField
I
investigate-metric

investigate-metric

github.com/posthogデータ・データベース76413 回インストール今日更新
リポジトリ

investigate-metric について

保存済みインサイト、ダッシュボードのタイル、クエリの数値変化を調べる PostHog スキルです。クエリの種類を判定し、通常の変動や関連する変更を確認したうえで、指標別の手順に沿って分析します。

主な機能

  1. 01対応する指標クエリの分類
  2. 02過去期間との変化比較
  3. 03フラグ、実験、注釈、Git 履歴の確認
  4. 04内訳セグメント別の変化分析
  5. 05原因仮説のクロスチェック

活用シーン

  1. 01保存済みインサイトの変化理由を調査
  2. 02コンバージョンやリテンションの変化を分析
  3. 03季節変動と異常を切り分け
  4. 04指標変化に関係するセグメントを特定

MCP 対応

PostHog MCP のクエリツールでトレンド、ファネル、リテンションなどを調べ、スキーマ、インサイト、関連するプロダクト変更の確認にもツールを使います。

インストール

コマンドをコピーしてターミナルで実行します。

$npx skills add https://github.com/posthog/skills --skill investigate-metric

インストール後、Claude Code で/investigate-metricを入力して読み込まれたか確認します。

同梱ファイル

SKILL.md と一緒にインストールされる参考資料やスクリプト。

references/
box-plot-playbook.md
common-causes.md
funnel-playbook.md
lifecycle-playbook.md
paths-playbook.md
retention-playbook.md
shared-patterns.md
stickiness-playbook.md
trend-playbook.md
scripts/
breakdown_attribution.py
compare_to_prior_periods.py

詳細

指標の変化を調査する

保存済みインサイト、ダッシュボードタイル、または貼り付けられたクエリについて、「X が変化したのはなぜ？」という質問に対応します。 単なる「X とは何ですか？」という質問では、このスキルを読み込まないでください。説明すべき変化が実際に確認されている場合にのみ使用します。

ツール

PostHog MCP v2 を対象とします。型付きクエリツールはクエリ本文を直接受け付けます。InsightVizNode でラップせず、kind、series、dateRange をトップレベルのフィールドとして渡してください。

ツール用途
posthog:query-trendsトレンド（時間ごとのカウント）
posthog:query-funnelファネル（複数ステップのコンバージョン）
posthog:query-retentionリテンション（コホートの再訪率）
posthog:query-stickinessスティッキネス（ユーザーごとのアクティブ日数）
posthog:query-lifecycleライフサイクル（新規／リピーター／復活／休眠）
posthog:query-pathsパス（ナビゲーションフロー）
posthog:query-trends-actorsトレンドのバケットに含まれるユーザー（トレンドのみ）
posthog:execute-sql既存の SQL インサイトとカスタム分析
posthog:read-data-schemaイベント、プロパティ、サンプル値の確認
posthog:insight-get / -query保存済みインサイトのメタデータ／データの取得

また、プレイブックで名前を挙げている標準の PostHog ツールもあります（feature-flag-get-all、 experiment-list、annotations-list、query-error-tracking-issues-list、query-logs、 query-session-recordings-list、cohorts-list/-create、annotation-create、 insight-create）。

ヘルパースクリプト

  • compare_to_prior_periods.py — 間隔を自動検出し、 直近の値を自然な周期（曜日、週内の時間帯、または連続した期間）と比較します。ステップ 2.2 を手早く解決するために使います。
  • breakdown_attribution.py — 内訳セグメントを絶対差分の大きい順に並べ、 相殺する変動にフラグを付けます。
python3 scripts/compare_to_prior_periods.py < query_result.json
WINDOW=7 python3 scripts/breakdown_attribution.py < breakdown_result.json

ステップ 1 — 指標を分類する

ユーザーが指定したソースから query.kind を読み取ります。

  • 保存済みインサイト（URL、short_id）：posthog:insight-get → query.kind。数値も必要な場合は posthog:insight-query を使います。
  • すでに実行したクエリ、またはユーザーが貼り付けたクエリ：kind を直接読み取ります。
  • 指定されたソースがない場合：URL または short_id を尋ねます。推測しないでください。
kindプレイブック
TrendsQuerytrend-playbook.md
FunnelsQueryfunnel-playbook.md
RetentionQueryretention-playbook.md
StickinessQuerystickiness-playbook.md
LifecycleQuerylifecycle-playbook.md
PathsQuerypaths-playbook.md
HogQLQuerySQL が集計する内容に応じて振り分けます（以下を参照）

kind === "TrendsQuery" かつ trendsFilter.display === "BoxPlot" の場合は、 box-plot-playbook.md を使います。対象は分布指標で、内訳はありません。

HogQLQuery インサイトは、SQL の形式で分類します。時間ごとのカウントならトレンドプレイブック、 複数ステップのコンバージョンならファネルプレイブック、コホートの再訪ならリテンションプレイブックを使います。 posthog:execute-sql で SQL を実行してデータを取得し、最も適したプレイブックの手順に従います。 shared-patterns.md の HogQL インサイトを参照してください。

ユーザーの質問が複数の種類にまたがる場合は、プレイブックを順番に実行します。

ステップ 2 — 共通の初動

2.1 異常を確認する

メインのツールを実行します。ベースライン、現在値、差分（絶対値と％）、および異常期間の開始時点を記録します。

2.2 変動を確認する

ユーザーが指定した期間の3～4倍に広げます（または、TrendsQuery / StickinessQuery で compareFilter: {"compare": true} を使用します。他の種類では、2つの日付範囲を指定して実行します）。 期間を広げた結果を compare_to_prior_periods.py に渡します。このスクリプトは、季節性、右端の不完全なバケット、実際の異常にフラグを立てます。変動が通常の範囲内であれば、その旨を報告して終了します。

2.3 期間中に確認された変更

シグナルの強さのおおよその順に示します。

  • posthog:feature-flag-get-all → 異常開始時点近くに updated_at があるフラグ。
  • posthog:experiment-list → 開始時点近くの start_date / end_date。
  • posthog:annotations-list → 開始時点近くの date_marker。
  • 期間中の git log（リポジトリにアクセスできる場合。利用可能なら最も強いシグナル）。

一致するものがあれば、プレイブックで仮説を確認します（通常は $feature/<flag_key>、app_version、または utm_source でブレークダウンします）。

Step 3 — プレイブックを実行する

Step 1 で特定した種類のプレイブックを開き、番号付きの手順に従います。2.1 の記録と、2.3 で見つかった候補をプレイブックに引き継ぎます。

Step 4 — クロスチェックする

疑わしい原因の影響を受けていないはずのセグメントを選び、そのセグメントで再実行します。対照群が安定していれば、有力な仮説です。そこでも変化していれば、調査範囲を広げます。2.2 ですでに変化の説明がついている場合は省略します。

Step 5 — 調査結果を記述する

以下の形式を使用します。主要なチャートを posthog:insight-create で保存することを提案します。原因が見つかり、それを示すアノテーションがない場合は、posthog:annotation-create の使用を提案します。原因の分類については、common-causes.md を参照してください。

# Investigation: <metric>

**Anomaly**: <baseline> → <current> (<delta>) starting <date>

## Likely cause

<one sentence>

**Confidence**: low | medium | high — <one-line reason>

**Evidence**

- <query result>
- <flag / experiment / annotation / commit if applicable>

## Possible causes (ruled out)

- <hypothesis>: <why>

## Affected segment

- <shared properties of affected users/events>

## Data gaps

- <checks skipped and why>

## Suggested follow-ups

- <concrete next action>
- <offer to save chart / create annotation>

確信度の目安：

  • 高 — 複数の独立したシグナルが裏付けている（例：セグメントで差分が特定され、さらにフラグ／バージョンが一致し、エラーまたはアノテーションも合致する）。
  • 中 — 裏付けるシグナルが1つある、またはクロスチェックはないものの、パターンが強く一致する。
  • 低 — 既知の原因とパターンが一致するが裏付けがない、またはデータから否定できることしかない。

インサイトとダッシュボードは、本文中に [Name](/insights/short_id) の形式でリンクします。

参照ファイル

コメント

Markdown 対応