investigate-metric

调查指标变化

适用于针对已保存的洞察、仪表板卡片或粘贴的查询提出的“X 为什么变了？”问题。 对于单纯询问“X 是什么？”的问题，不要加载此技能——仅在需要解释已观察到的变化时使用。

工具

目标为 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	现有 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	操作指南
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 洞察。

如果用户的问题涉及多种类型，请依次运行相应的操作指南。

第 2 步 — 通用开场步骤

2.1 确认异常

运行主要工具。记录基线、当前值、变化量（绝对值和百分比），以及异常窗口的开始时间。

2.2 检查波动

将时间范围扩大到用户所选间隔的 3–4 倍（或在 TrendsQuery / StickinessQuery 上使用 compareFilter: {"compare": true}；对于其他类型，运行两个日期范围）。 将扩大后的结果传入 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 进行细分）。

第 3 步 — 运行操作手册

打开第 1 步中对应类型的操作手册，并按编号步骤执行。将 2.1 中的记录和 2.3 中的候选项一并带入。

第 4 步 — 交叉验证

选择一个不应受到疑似原因影响的细分群体，并在其中重新运行。对照组保持稳定 = 强有力的假设；对照组也发生变化 = 扩大调查范围。如果 2.2 已经解释了变化，则跳过此步。

第 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>

置信度参考规则：

• 高 — 多个独立信号相互印证（例如，某个细分群体能够隔离出变化量，且某个标记或版本与之吻合，并且错误或注释也相符）。
• 中 — 有一个佐证信号，或模式高度吻合但未经交叉验证。
• 低 — 模式符合某种已知原因，但没有佐证；或数据只能排除某些原因。

在正文中内嵌链接，引用洞察和仪表板：[名称](/insights/short_id)。

参考文件

• 操作手册：趋势、 箱线图、 漏斗、 留存、 粘性、 生命周期、 路径
• shared-patterns.md — 各操作手册通用的方案
• common-causes.md — 原因分类及用于确认的查询