Back to Details

investigate-metric

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

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.
针对关于已保存洞察、仪表板组件或粘贴查询的“X为什么变化？”类问题。 仅当需要解释已观测到的变化时才启用此技能，不要用于单纯的“X是什么？”类问题。

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-trends
Trends (count over time)
posthog:query-funnel
Funnels (multi-step conversion)
posthog:query-retention
Retention (cohort return rates)
posthog:query-stickiness
Stickiness (active days per user)
posthog:query-lifecycle
Lifecycle (new/returning/resurrecting/dormant)
posthog:query-paths
Paths (navigation flow)
posthog:query-trends-actors
Users behind a trend bucket (trends source only)
posthog:execute-sql
HogQL — when no typed tool fits
posthog:read-data-schema
Discover events, properties, sample values
posthog:insight-get
/ 
-query
Fetch 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
, 
error-tracking-issues-list
, 
query-logs
, 
query-session-recordings-list
, 
cohorts-list/-create
, 
annotation-create
, 
insight-create
).
目标为PostHog MCP v2。类型化查询工具直接接受查询主体——将
kind
、
series
、
dateRange
作为顶级字段传递，不要包裹在
InsightVizNode
中。
工具名称用途
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
HogQL——当没有合适的类型化工具时使用
posthog:read-data-schema
发现事件、属性、样本值
posthog:insight-get
/ 
-query
获取已保存洞察的元数据 / 数据
此外，还有剧本中按名称引用的标准PostHog工具：
feature-flag-get-all
、
experiment-get-all
、
annotations-list
、
error-tracking-issues-list
、
query-logs
、
query-session-recordings-list
、
cohorts-list/-create
、
annotation-create
、
insight-create
。

Helper scripts

辅助脚本

  • compare_to_prior_periods.py
     — auto-detects interval and compares recent values to the natural cycle (day-of-week, hour-of-week, or sequential). Use to resolve step 2.2 cheaply.
  • breakdown_attribution.py
     — ranks breakdown 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
  • compare_to_prior_periods.py
     — 自动检测时间间隔，并将近期值与自然周期（星期几、一周中的小时或连续周期）进行比较。用于低成本完成步骤2.2。
  • breakdown_attribution.py
     — 按绝对差值对细分组进行排名，并标记抵消性变动。
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

步骤1 — 分类指标

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
TrendsQuery
trend-playbook.md
FunnelsQuery
funnel-playbook.md
RetentionQuery
retention-playbook.md
StickinessQuery
stickiness-playbook.md
LifecycleQuery
lifecycle-playbook.md
PathsQuery
paths-playbook.md
HogQLQuery
route 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.
从用户指向的来源中读取
query.kind
：
  • 已保存洞察（URL、
    short_id
    ）：调用
    posthog:insight-get
    → 获取
    query.kind
    。如果还需要数据，使用
    posthog:insight-query
    。
  • 已运行的查询或用户粘贴的查询：直接读取
    kind
    。
  • 未指向任何来源：询问URL或short_id，不要猜测。
kind剧本链接
TrendsQuery
trend-playbook.md
FunnelsQuery
funnel-playbook.md
RetentionQuery
retention-playbook.md
StickinessQuery
stickiness-playbook.md
LifecycleQuery
lifecycle-playbook.md
PathsQuery
paths-playbook.md
HogQLQuery
根据SQL聚合的内容选择对应剧本（见下文）
如果
kind === "TrendsQuery"
且
trendsFilter.display === "BoxPlot"
，使用box-plot-playbook.md —— 这是分布类指标，无需细分。
对于
HogQLQuery
洞察，根据SQL的结构进行分类：随时间计数→趋势剧本，多步骤转化→漏斗剧本，群组回访→留存剧本。调用
posthog:execute-sql
运行SQL获取数据，然后遵循最接近的剧本步骤。详见shared-patterns.md中的HogQL洞察部分。
如果用户的问题涉及多种类型，依次运行对应的剧本。

Step 2 — Common opening moves

步骤2 — 通用开场操作

2.1 Confirm the anomaly

2.1 确认异常

Run the primary tool. Record baseline, current, delta (absolute and %), and the start of the anomaly window.
运行主工具。记录基线值、当前值、差值（绝对差值和百分比）以及异常窗口的开始时间。

2.2 Variance check

2.2 方差检查

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.
将时间范围扩大到用户指定间隔的3-4倍（或在TrendsQuery / StickinessQuery中使用
compareFilter: {"compare": true}
；对于其他类型，运行两个日期范围）。 将扩大范围后的结果传入
compare_to_prior_periods.py
 —— 该脚本会标记季节性、右边缘部分时间段和真实异常。如果变动属于正常方差，直接报告并停止分析。

2.3 Known changes in the window

2.3 窗口内的已知变化

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
).
按信号强度从高到低排序：
  • posthog:feature-flag-get-all
    → 查找
    updated_at
    接近异常开始时间的功能标志。
  • posthog:experiment-get-all
    → 查找
    start_date
    / 
    end_date
    接近异常开始时间的实验。
  • posthog:annotations-list
    → 查找
    date_marker
    接近异常开始时间的注释。
  • 如果可访问代码仓库，查看该窗口内的
    git log
    （可用时信号强度最高）。
任何匹配项都是需要在剧本中验证的假设（通常通过按
$feature/<flag_key>
、
app_version
或
utm_source
进行细分来验证）。

Step 3 — Run the playbook

步骤3 — 执行剧本

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.
打开步骤1中对应类型的剧本，按照编号步骤执行。将2.1中记录的数据和2.3中找到的候选原因带入剧本。

Step 4 — Cross-check

步骤4 — 交叉验证

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.
选择一个疑似原因不应影响的细分群体，重新运行分析。对照组数据稳定→假设可信度高；对照组数据也变动→扩大调查范围。如果2.2已经解释了变动原因，可跳过此步骤。

Step 5 — Write findings

步骤5 — 撰写调查结果

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
undefined
使用以下格式。可通过
posthog:insight-create
保存关键图表。如果找到原因且没有对应的注释，可通过
posthog:annotation-create
添加注释。原因分类详见common-causes.md。
markdown
undefined

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)`.
  • <具体下一步行动>
  • <提供保存图表/创建注释的选项>

**可信度**经验法则：

- **高** — 多个独立信号相互佐证（例如，某细分群体隔离出差值 _且_ 功能标志/版本时间吻合 _且_ 存在匹配的错误或注释）。
- **中** — 有一个佐证信号，或有强烈的模式匹配但未进行交叉验证。
- **低** — 模式匹配已知原因但无佐证，或数据仅排除了部分可能性。

在文中链接洞察和仪表板：`[名称](/insights/short_id)`。

Reference files

参考文件

  • Playbooks: trend, box-plot, funnel, retention, stickiness, lifecycle, paths
  • shared-patterns.md — recipes used across playbooks
  • common-causes.md — cause taxonomy with confirming queries
  • 剧本：趋势、箱线图、漏斗、留存、粘性、生命周期、路径
  • shared-patterns.md — 各剧本通用的方法
  • common-causes.md — 包含验证查询的原因分类