posthog/ai-plugin

investigate-metric

Diagnose why a product metric changed (dropped, spiked, or plateaued) by orchestrating breakdowns, actors, paths, lifecycle, retention, and annotations queries.

소스 보기

사용 방법

  1. 설치 명령을 복사하고 자신의 에이전트 환경에 설치하기 전에 소스 패키지를 확인하세요.
  2. 필요한 도구, 인증 정보, 지원 환경은 원본 문서에서 확인하세요.
  3. 입력과 원하는 산출물을 설명하고 출처와 결과를 대조하세요.
npx skills add https://github.com/posthog/ai-plugin --skill investigate-metric

시작 전 확인

  • 설치에는 모델 구독, API 한도, 파일 접근 권한이 포함되지 않습니다.
  • 별점 수와 설치 수는 활동 지표이며 독립적인 품질·보안 검증이 아닙니다.
원본 Skill 문서

원본 저장소의 제목, 예시, 코드, 표, 링크, 이미지를 유지해 표시합니다.

Investigating a metric change

For "why did X change?" questions about a saved insight, dashboard tile, or pasted query. Don't load this skill for plain "what is X?" questions — only when there's an observed change to explain.

Tools

Targets PostHog MCP v2. Typed query tools accept the query body directly — pass kind, series, dateRange as top-level fields, do not wrap in InsightVizNode.

ToolPurpose
posthog:query-trendsTrends (count over time)
posthog:query-funnelFunnels (multi-step conversion)
posthog:query-retentionRetention (cohort return rates)
posthog:query-stickinessStickiness (active days per user)
posthog:query-lifecycleLifecycle (new/returning/resurrecting/dormant)
posthog:query-pathsPaths (navigation flow)
posthog:query-trends-actorsUsers behind a trend bucket (trends source only)
posthog:execute-sqlHogQL — when no typed tool fits
posthog:read-data-schemaDiscover events, properties, sample values
posthog:insight-get / -queryFetch a saved insight's metadata / data

Plus the standard PostHog tools the playbooks reference by name (feature-flag-get-all, experiment-get-all, annotations-list, query-error-tracking-issues-list, query-logs, query-session-recordings-list, cohorts-list/-create, annotation-create, insight-create).

Helper scripts

interval and compares recent values to the natural cycle (day-of-week, hour-of-week, or sequential). Use to resolve step 2.2 cheaply.

segments by absolute delta and flags offsetting moves.

bash
python3 scripts/compare_to_prior_periods.py < query_result.json
WINDOW=7 python3 scripts/breakdown_attribution.py < breakdown_result.json

Step 1 — Classify the metric

Read query.kind from the source the user pointed at:

  • Saved insight (URL, short_id): posthog:insight-get → query.kind. Use

posthog:insight-query if you also need the numbers.

  • A query you already ran or the user pasted: read kind directly.
  • Nothing pointed at: ask for the URL or short_id. Don't guess.
kindPlaybook
TrendsQuerytrend-playbook.md
FunnelsQueryfunnel-playbook.md
RetentionQueryretention-playbook.md
StickinessQuerystickiness-playbook.md
LifecycleQuerylifecycle-playbook.md
PathsQuerypaths-playbook.md
HogQLQueryroute by what the SQL aggregates (see below)

If kind === "TrendsQuery" and trendsFilter.display === "BoxPlot", use box-plot-playbook.md — distribution metric, no breakdowns.

For HogQLQuery insights, classify by the SQL's shape: count over time → trend playbook, multi-step conversion → funnel playbook, cohort return → retention playbook. Run the SQL through posthog:execute-sql to get the data, then follow the closest playbook's steps. See HogQL insights in shared-patterns.md.

If the user's question spans multiple kinds, run the playbooks in sequence.

Step 2 — Common opening moves

2.1 Confirm the anomaly

Run the primary tool. Record baseline, current, delta (absolute and %), and the start of the anomaly window.

2.2 Variance check

Widen to 3–4× the user's interval (or use compareFilter: {"compare": true} on TrendsQuery / StickinessQuery; for other kinds run two date ranges). Pipe the widened result through `compare_to_prior_periods.py` — it flags seasonality, partial right-edge buckets, and real anomalies. If the movement is normal variance, report that and stop.

2.3 Known changes in the window

In rough order of signal:

  • posthog:feature-flag-get-all → flags with updated_at near the anomaly start.
  • posthog:experiment-get-all → start_date / end_date near the start.
  • posthog:annotations-list → date_marker near the start.
  • git log for the window if the repo is reachable (highest signal when available).

Any match is a hypothesis to confirm in the playbook (usually via breakdown on $feature/<flag_key>, app_version, or utm_source).

Step 3 — Run the playbook

Open the playbook for the kind from Step 1 and follow its numbered steps. Carry the record from 2.1 and any candidates from 2.3 into it.

Step 4 — Cross-check

Pick a segment the suspected cause should not have affected and rerun there. Stable in the control = strong hypothesis; moved too = expand the investigation. Skip when 2.2 already explained the movement.

Step 5 — Write findings

Use the format below. Offer to save key charts via posthog:insight-create. If a cause is found and no annotation marks it, offer posthog:annotation-create. See common-causes.md for the cause taxonomy.

markdown
# 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>

Confidence rule of thumb:

  • high — multiple independent signals corroborate (e.g. a segment isolates the

delta and a flag/version aligns and an error or annotation matches).

  • medium — one corroborating signal, or strong pattern-match without a

cross-check.

  • low — pattern matches a known cause but no corroboration, or the data only

rules things out.

Link insights and dashboards inline: [Name](/insights/short_id).

Reference files

box-plot, funnel, retention, stickiness, lifecycle, paths

관련 작업

같은 저장소의 Skills

더 많은 Skills

모든 Skills
posthog
공식

exploring-llm-costs

Investigate LLM spend in PostHog — total cost over time, cost by model, provider, user, trace, or custom dimension, token and cache-hit economics, and cost regressions. Use when the user asks "how much are we spending on LLMs?", "which model / user / feature is most expensive?", "why did cost spike?", wants to build a cost dashboard or alert, or pastes a trace URL and asks about its cost.

1시간 설치 수
2
GitHub Stars
98
업데이트
11월 6일
posthog
공식

exploring-llm-traces

Debug and inspect LLM/AI agent traces using PostHog's MCP tools. Use when the user pastes a trace or session URL (e.g. /ai-observability/traces/ or /ai-observability/sessions/ ), asks to debug a trace, figure out what went wrong, check if an agent used a tool correctly, verify context/files were surfaced, inspect subagent behavior, investigate LLM decisions, or analyze token usage and costs. Also use when raw SQL/HogQL against events.properties.$aiinput / $aioutputchoices returns empty — message

1시간 설치 수
2
GitHub Stars
98
업데이트
11월 6일
posthog
공식

instrument-integration

Add PostHog SDK integration to your application. Use when setting up PostHog for the first time or reviewing PRs that need PostHog initialization. Covers SDK installation, provider setup, and basic configuration for any framework.

1시간 설치 수
2
GitHub Stars
98
업데이트
11월 6일
posthog
공식

investigating-error-issue

Investigates a single PostHog error tracking issue end-to-end. Use when the user provides an issue ID or pastes an issue URL (/error-tracking/ ) and wants to understand the error — who it affects, what triggers it, when it started, whether it correlates with a release, browser, OS, or feature flag, and what the next step should be. Pulls aggregated metrics, sample exception events, segment breakdowns, linked replays, and synthesizes a hypothesis-grade summary in one pass.

1시간 설치 수
2
GitHub Stars
98
업데이트
11월 6일