[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"skill-posthog-configuring-experiment-analytics":3,"mdc--pvy1h5-key":41,"related-repo-posthog-configuring-experiment-analytics":1397,"related-org-posthog-configuring-experiment-analytics":1515},{"slug":4,"name":4,"fn":5,"description":6,"org":7,"tags":11,"stars":26,"repoUrl":27,"updatedAt":28,"license":29,"forks":30,"topics":31,"repo":36,"sourceUrl":39,"mdContent":40},"configuring-experiment-analytics","configure PostHog experiment analytics","Configures the analytics side of a PostHog experiment — exposure criteria (default `$feature_flag_called` vs custom exposure events), primary and secondary metrics, the supported metric types (count, sum, ratio with `math` and `math_property`, retention with `retention_window_start` and `start_handling`), multivariate user handling (\"Exclude\" vs \"First seen variant\"), and how to read results once the experiment is live. Use when the user adds or edits a primary or secondary metric (e.g. \"add a secondary metric tracking 'downloaded_file' per user\"), sets up a ratio metric (e.g. \"revenue from purchase_completed \u002F pageviews\"), sets up a retention metric (e.g. \"$pageview → uploaded_file, 7-day window\"), configures custom exposure (e.g. \"only count users who hit \u002Fcheckout\"), changes multivariate handling, or asks \"who is in the analysis?\", \"how do I measure impact?\", \"is this winning?\", \"what's the confidence level?\", or \"should I ship?\".",{"slug":8,"name":9,"logoUrl":10,"githubOrg":8},"posthog","PostHog","https:\u002F\u002Fpexgzepcugksgbtrxkhf.supabase.co\u002Fstorage\u002Fv1\u002Fobject\u002Fpublic\u002Forg-logos\u002Fposthog.png",[12,14,17,20,23],{"name":9,"slug":8,"type":13},"tag",{"name":15,"slug":16,"type":13},"Reporting","reporting",{"name":18,"slug":19,"type":13},"Data Analysis","data-analysis",{"name":21,"slug":22,"type":13},"Analytics","analytics",{"name":24,"slug":25,"type":13},"A\u002FB Testing","a-b-testing",59,"https:\u002F\u002Fgithub.com\u002FPostHog\u002Fai-plugin","2026-04-24T05:16:52.666341",null,11,[32,33,34,35],"claude-code-plugin","codex-plugin","cursor-plugin","gemini-cli-extension",{"repoUrl":27,"stars":26,"forks":30,"topics":37,"description":38},[32,33,34,35],"Official PostHog plugin for Claude Code, Cursor, Gemini, Codex and other AI coding tools","https:\u002F\u002Fgithub.com\u002FPostHog\u002Fai-plugin\u002Ftree\u002FHEAD\u002Fskills\u002Fconfiguring-experiment-analytics","---\nname: configuring-experiment-analytics\ndescription: Configures the analytics side of a PostHog experiment — exposure criteria (default `$feature_flag_called` vs custom exposure events), primary and secondary metrics, the supported metric types (count, sum, ratio with `math` and `math_property`, retention with `retention_window_start` and `start_handling`), multivariate user handling (\"Exclude\" vs \"First seen variant\"), and how to read results once the experiment is live. Use when the user adds or edits a primary or secondary metric (e.g. \"add a secondary metric tracking 'downloaded_file' per user\"), sets up a ratio metric (e.g. \"revenue from purchase_completed \u002F pageviews\"), sets up a retention metric (e.g. \"$pageview → uploaded_file, 7-day window\"), configures custom exposure (e.g. \"only count users who hit \u002Fcheckout\"), changes multivariate handling, or asks \"who is in the analysis?\", \"how do I measure impact?\", \"is this winning?\", \"what's the confidence level?\", or \"should I ship?\".\n---\n\n# Configuring experiment analytics\n\nThis skill answers: **Who is included in the analysis?** and **How to measure impact?**\n\n## Exposure criteria\n\nExposure criteria determine which users are counted in the experiment analysis.\n\n### Include people when\n\nTwo options:\n\n1. **Feature flag called** (default) — users are included when the `$feature_flag_called` event fires for the experiment's flag. This is the standard approach — it means a user is included only when they actually encounter the feature flag in your code.\n2. **Custom exposure event** — users are included when a specific custom event fires. Use this when you want tighter control over who enters the analysis (e.g., only users who actually visit the page where the experiment runs).\n\n### Multiple variant handling\n\nWhen a user is exposed to multiple variants (e.g., due to flag changes or race conditions):\n\n- **Exclude multivariate users** — removes these users from the analysis entirely. Cleaner data, smaller sample.\n- **First seen variant** — assigns users to the first variant they were exposed to. Keeps all users in the analysis. Note that \"first seen\" can introduce other biases as\n  behavior cannot be clearly attributed to a single variant and is not recommended unless necessary.\n\n**Bias risk on uneven splits.** \"Exclude multivariate users\" combined with an uneven variant split can\nintroduce bias — multi-variant users are dropped asymmetrically and the smaller variant loses a larger\nfraction of its assignments. If those users behave differently from the rest, the smaller variant's\nmetrics will be skewed.\n\nThe right mitigation depends on experiment state:\n\n- **Not yet launched, or only exposed to a few users so far** — switch to an even variant split and\n  use the overall rollout percentage to limit test-variant exposure. This removes the bias and\n  preserves statistical power. See `configuring-experiment-rollout`.\n- **Live experiment with significant exposures** — changing the split mid-run reassigns users across\n  variants, which is bad for user experience and data quality. Switch this setting to \"First seen\n  variant\" instead — it keeps already-assigned users in their original variant (no reassignment) and\n  removes the asymmetric exclusion.\n\n### Filter test accounts\n\n`exposure_criteria.filterTestAccounts` (default: true) — excludes internal\u002Ftest users from the analysis.\n\n## Resolving experiments\n\nMetric changes require an experiment ID. If the user refers to an experiment by name\nor description (e.g. \"add metrics to the checkout test\"), load the `finding-experiments`\nskill to resolve it to a concrete ID before proceeding.\n\n## Metrics\n\nA metric reaches an experiment one of two ways, both via `experiment-update`:\n\n- **Inline metric** — defined directly on the experiment. Sent in the `metrics` array, which\n  **replaces** the entire inline list, so always get the current experiment first via `experiment-get`\n  to preserve existing metrics.\n- **Shared (saved) metric** — a reusable metric object that can be attached to many experiments.\n  Attached by ID via `saved_metrics_ids` (this list also **replaces** the experiment's existing\n  saved-metric links, so resend the full set — see Step 1).\n\n**Prefer reusing a shared metric over duplicating it inline.** Build a new inline metric only when\nno suitable shared metric already exists.\n\n### Step 1: Check for an existing shared metric (REQUIRED — match by definition, not name)\n\nBefore building any new inline metric, you MUST check whether the project already has a shared\n(saved) metric that measures the same thing, and reuse it. Duplicating a metric that already exists\nas a shared metric fragments measurement and is exactly what we want to avoid.\n\n**Reuse is decided by the metric _definition_ — the event or action plus the metric type — not the\nname.** Saved metrics are named by each team's own conventions, which you cannot guess, so you must\ncompare on what each metric measures (its `query`), never on its title.\n\n**Workflow:**\n\n1. **Know what you're about to build first.** Settle the target event(s)\u002Faction(s) and metric type\n   (mean \u002F funnel \u002F ratio \u002F retention) before searching — see Step 2 to confirm the event exists via\n   `read-data-schema`. You can only recognize a duplicate once you know the concrete event\u002Faction,\n   so this check runs _after_ you've pinned down the event, not before.\n2. **Search by the event, then compare each candidate's `query`.** Call `experiment-saved-metrics-list`\n   with `?event=\u003Cthe event you're measuring>` to find metrics that reference it — matched directly (an\n   `EventsNode`) **or** via the step events of any action a metric references, so action-based metrics are\n   found by the event their action fires on. Then for each returned row, inspect its **`query`** (not the\n   `name`\u002F`description`): a saved metric is a reuse match when its `query` measures the **same event or\n   action with the same `metric_type`** (and compatible `math`) as the metric you'd otherwise build, even\n   if its name is different.\n   - **Match on the event, not the action's name.** An action-based metric is discoverable by the event\n     the action fires on — pass that event, not the action's label.\n   - **Do not use `search` for this.** `search` matches only the metric's own `name` \u002F `description` \u002F tags —\n     never the underlying event or action — so it cannot find a definition match. Use `search` only when the\n     user names a specific saved metric to attach (name resolution, not a definition match).\n3. **If a saved metric matches the definition** — confirm the match with the user by name\u002Fdescription,\n   then attach it instead of building a new one:\n   - Call `experiment-get` to read the experiment's current `saved_metrics`.\n   - Call `experiment-update` with `saved_metrics_ids` set to the full desired set — it **replaces**\n     existing links, so include the already-attached ones plus the new entry. Each entry has shape\n     `{ \"id\": \u003Csaved-metric id>, \"metadata\": { \"type\": \"primary\" } }` — set `type` to `\"primary\"` or\n     `\"secondary\"`. `metadata` is optional and defaults to primary.\n   - **Watch the id when rebuilding the set:** each item in the `saved_metrics` you just read has a\n     top-level `id` (the _link_ id) AND a `saved_metric` field (the _metric_ id). `saved_metrics_ids`\n     wants the **`saved_metric`** value, not the link `id` — sending the link `id` attaches the wrong\n     metric or fails validation.\n   - You do not need to build the inline metric — the shared metric already encodes its events.\n4. **If nothing in the library measures the same event\u002Faction + type** — build an inline metric\n   (Step 2+). When that inline metric is likely to be reused across experiments, offer to create it\n   as a shared metric instead, via `experiment-saved-metrics-create`, then attach it as above, so the\n   next experiment can reuse it.\n\n### Step 2: Discover available events (REQUIRED before building an inline metric)\n\nBefore suggesting or building any new inline metric, you MUST call `read-data-schema` to discover\nwhat events actually exist in the project. Do NOT skip this step. Do NOT suggest event names\nbased on what you think the project might track — only use events you have confirmed exist.\n(Attaching an existing shared metric from Step 1 does not need this — it already encodes its events.)\n\nThis applies even when:\n\n- The user provides event names — look them up to confirm they exist and are spelled correctly\n- The user asks \"what metrics do you suggest?\" — look up events first, then suggest from real data\n- The context makes certain events seem obvious — they may not exist or may be named differently\n\n**Workflow:**\n\n1. Call `read-data-schema` to get the project's events\n2. Present relevant events to the user based on the experiment's hypothesis\n3. User picks which events to use for metrics\n4. Configure metrics with those confirmed event names\n\n**Legitimate exception — `allow_unknown_events: true`:**\nPass this on `experiment-create` \u002F `experiment-update` only when the user is intentionally instrumenting an event that hasn't been ingested yet (e.g. setting up the experiment before the code change ships). Confirm this with the user — never use it as a workaround for \"the event lookup didn't return what I expected\".\n\n**Example:**\n\n```text\nUser: \"Let's add some metrics for the checkout experiment\"\n\nWRONG: \"I'd suggest using purchase_completed as the primary metric...\"\n  (hallucinated event name — never seen the project's actual events)\n\nRIGHT: *calls read-data-schema* → \"Here are the events in your project\n  related to checkout: `checkout_step_completed`, `payment_processed`,\n  `order_confirmed`. Which of these represents a successful checkout?\"\n```\n\n### Step 3: Choose metric type\n\nThere are four metric types. Each has `kind: \"ExperimentMetric\"`:\n\n| metric_type   | When to use                                                                            | Required fields                                                                                                                |\n| ------------- | -------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------ |\n| `\"mean\"`      | Average of a numeric property per user (revenue, session duration, pageviews per user) | `source`                                                                                                                       |\n| `\"funnel\"`    | Conversion rate from exposure through one or more ordered actions                      | `series` (1 or more steps)                                                                                                     |\n| `\"ratio\"`     | Rate of one event relative to another                                                  | `numerator`, `denominator` — set `math: \"sum\"` + `math_property` on a side to aggregate a property; filters never aggregate    |\n| `\"retention\"` | Do users come back after exposure?                                                     | `start_event`, `completion_event`, `retention_window_start`, `retention_window_end`, `retention_window_unit`, `start_handling` |\n\n**Funnel metrics and the implicit exposure step**\n\nFunnel metrics automatically prepend the experiment's exposure event as `step_0`.\nSo a funnel with 1 step in `series` is a valid 2-step funnel: **exposure → action**.\nThis is the correct choice for measuring \"what percentage of exposed users did X?\"\n\nExamples:\n\n- \"What % of exposed users reached \u002Flogin?\" → funnel with 1 step (`$pageview` filtered to \u002Flogin)\n- \"What % of exposed users completed checkout?\" → funnel with 1 step (`checkout_completed`)\n- \"What % of exposed users went cart → checkout → purchase?\" → funnel with 3 steps\n\n**Mean vs funnel for the same event**\n\n- **Mean** measures average count\u002Fvalue per user (e.g. \"pageviews per user\", \"revenue per user\").\n- **Funnel** measures conversion rate (e.g. \"% of exposed users who purchased\").\n\nBoth can reference the same event — the difference is whether you care about count\u002Fmagnitude (mean) or yes\u002Fno conversion (funnel).\n\n**Retention: same vs different start\u002Fcompletion event**\n\nThe retention window is measured from the start event, so the events you pick decide what's measured:\nThe start occurrence never counts as its own completion (only a distinct later event does), so both shapes are valid:\n\n- **Different** start and completion events → conversion-style retention (\"did they reach the target action within the window?\").\n- **Same** event → repeat retention (\"did they fire it _again_?\"). `From 0` counts a repeat from the same period onward (same-day repeats included); `From ≥ 1` requires an occurrence later. Use `start_handling: \"first_seen\"`. When a user says \"retention of `\u003Cevent>`\" they usually mean repeat retention.\n\nSee `references\u002Fmetric-configuration.md` for the full rendered `ExperimentMetric` schema (all four metric types, with required fields per type) plus WRONG\u002FRIGHT JSON pairs for the failure modes that come up most often (ratio with `is_set` filter instead of `math: \"sum\"` + `math_property`; retention without `retention_window_start` \u002F `start_handling`). Read it before assembling a ratio or retention payload — the required fields are authoritative.\n\n### Step 4: Primary vs secondary\n\n- **Primary metrics** — the main success criteria for the experiment. These drive the ship\u002Fend decision.\n- **Secondary metrics** — additional measurements for context. Useful for guardrail metrics (e.g., ensuring a conversion improvement doesn't increase error rates).\n\n## Interpreting results\n\nSee `references\u002Finterpreting-results.md` for guidance on reading experiment results, statistical significance, and when to ship vs end.\n",{"data":42,"body":43},{"name":4,"description":6},{"type":44,"children":45},"root",[46,54,73,80,85,92,97,131,137,142,166,176,181,212,218,229,235,248,254,267,326,336,342,347,373,381,766,772,784,789,807,814,843,874,882,894,900,912,1110,1118,1145,1150,1184,1192,1215,1220,1228,1233,1295,1350,1356,1379,1385],{"type":47,"tag":48,"props":49,"children":50},"element","h1",{"id":4},[51],{"type":52,"value":53},"text","Configuring experiment analytics",{"type":47,"tag":55,"props":56,"children":57},"p",{},[58,60,66,68],{"type":52,"value":59},"This skill answers: ",{"type":47,"tag":61,"props":62,"children":63},"strong",{},[64],{"type":52,"value":65},"Who is included in the analysis?",{"type":52,"value":67}," and ",{"type":47,"tag":61,"props":69,"children":70},{},[71],{"type":52,"value":72},"How to measure impact?",{"type":47,"tag":74,"props":75,"children":77},"h2",{"id":76},"exposure-criteria",[78],{"type":52,"value":79},"Exposure criteria",{"type":47,"tag":55,"props":81,"children":82},{},[83],{"type":52,"value":84},"Exposure criteria determine which users are counted in the experiment analysis.",{"type":47,"tag":86,"props":87,"children":89},"h3",{"id":88},"include-people-when",[90],{"type":52,"value":91},"Include people when",{"type":47,"tag":55,"props":93,"children":94},{},[95],{"type":52,"value":96},"Two options:",{"type":47,"tag":98,"props":99,"children":100},"ol",{},[101,121],{"type":47,"tag":102,"props":103,"children":104},"li",{},[105,110,112,119],{"type":47,"tag":61,"props":106,"children":107},{},[108],{"type":52,"value":109},"Feature flag called",{"type":52,"value":111}," (default) — users are included when the ",{"type":47,"tag":113,"props":114,"children":116},"code",{"className":115},[],[117],{"type":52,"value":118},"$feature_flag_called",{"type":52,"value":120}," event fires for the experiment's flag. This is the standard approach — it means a user is included only when they actually encounter the feature flag in your code.",{"type":47,"tag":102,"props":122,"children":123},{},[124,129],{"type":47,"tag":61,"props":125,"children":126},{},[127],{"type":52,"value":128},"Custom exposure event",{"type":52,"value":130}," — users are included when a specific custom event fires. Use this when you want tighter control over who enters the analysis (e.g., only users who actually visit the page where the experiment runs).",{"type":47,"tag":86,"props":132,"children":134},{"id":133},"multiple-variant-handling",[135],{"type":52,"value":136},"Multiple variant handling",{"type":47,"tag":55,"props":138,"children":139},{},[140],{"type":52,"value":141},"When a user is exposed to multiple variants (e.g., due to flag changes or race conditions):",{"type":47,"tag":143,"props":144,"children":145},"ul",{},[146,156],{"type":47,"tag":102,"props":147,"children":148},{},[149,154],{"type":47,"tag":61,"props":150,"children":151},{},[152],{"type":52,"value":153},"Exclude multivariate users",{"type":52,"value":155}," — removes these users from the analysis entirely. Cleaner data, smaller sample.",{"type":47,"tag":102,"props":157,"children":158},{},[159,164],{"type":47,"tag":61,"props":160,"children":161},{},[162],{"type":52,"value":163},"First seen variant",{"type":52,"value":165}," — assigns users to the first variant they were exposed to. Keeps all users in the analysis. Note that \"first seen\" can introduce other biases as\nbehavior cannot be clearly attributed to a single variant and is not recommended unless necessary.",{"type":47,"tag":55,"props":167,"children":168},{},[169,174],{"type":47,"tag":61,"props":170,"children":171},{},[172],{"type":52,"value":173},"Bias risk on uneven splits.",{"type":52,"value":175}," \"Exclude multivariate users\" combined with an uneven variant split can\nintroduce bias — multi-variant users are dropped asymmetrically and the smaller variant loses a larger\nfraction of its assignments. If those users behave differently from the rest, the smaller variant's\nmetrics will be skewed.",{"type":47,"tag":55,"props":177,"children":178},{},[179],{"type":52,"value":180},"The right mitigation depends on experiment state:",{"type":47,"tag":143,"props":182,"children":183},{},[184,202],{"type":47,"tag":102,"props":185,"children":186},{},[187,192,194,200],{"type":47,"tag":61,"props":188,"children":189},{},[190],{"type":52,"value":191},"Not yet launched, or only exposed to a few users so far",{"type":52,"value":193}," — switch to an even variant split and\nuse the overall rollout percentage to limit test-variant exposure. This removes the bias and\npreserves statistical power. See ",{"type":47,"tag":113,"props":195,"children":197},{"className":196},[],[198],{"type":52,"value":199},"configuring-experiment-rollout",{"type":52,"value":201},".",{"type":47,"tag":102,"props":203,"children":204},{},[205,210],{"type":47,"tag":61,"props":206,"children":207},{},[208],{"type":52,"value":209},"Live experiment with significant exposures",{"type":52,"value":211}," — changing the split mid-run reassigns users across\nvariants, which is bad for user experience and data quality. Switch this setting to \"First seen\nvariant\" instead — it keeps already-assigned users in their original variant (no reassignment) and\nremoves the asymmetric exclusion.",{"type":47,"tag":86,"props":213,"children":215},{"id":214},"filter-test-accounts",[216],{"type":52,"value":217},"Filter test accounts",{"type":47,"tag":55,"props":219,"children":220},{},[221,227],{"type":47,"tag":113,"props":222,"children":224},{"className":223},[],[225],{"type":52,"value":226},"exposure_criteria.filterTestAccounts",{"type":52,"value":228}," (default: true) — excludes internal\u002Ftest users from the analysis.",{"type":47,"tag":74,"props":230,"children":232},{"id":231},"resolving-experiments",[233],{"type":52,"value":234},"Resolving experiments",{"type":47,"tag":55,"props":236,"children":237},{},[238,240,246],{"type":52,"value":239},"Metric changes require an experiment ID. If the user refers to an experiment by name\nor description (e.g. \"add metrics to the checkout test\"), load the ",{"type":47,"tag":113,"props":241,"children":243},{"className":242},[],[244],{"type":52,"value":245},"finding-experiments",{"type":52,"value":247},"\nskill to resolve it to a concrete ID before proceeding.",{"type":47,"tag":74,"props":249,"children":251},{"id":250},"metrics",[252],{"type":52,"value":253},"Metrics",{"type":47,"tag":55,"props":255,"children":256},{},[257,259,265],{"type":52,"value":258},"A metric reaches an experiment one of two ways, both via ",{"type":47,"tag":113,"props":260,"children":262},{"className":261},[],[263],{"type":52,"value":264},"experiment-update",{"type":52,"value":266},":",{"type":47,"tag":143,"props":268,"children":269},{},[270,302],{"type":47,"tag":102,"props":271,"children":272},{},[273,278,280,285,287,292,294,300],{"type":47,"tag":61,"props":274,"children":275},{},[276],{"type":52,"value":277},"Inline metric",{"type":52,"value":279}," — defined directly on the experiment. Sent in the ",{"type":47,"tag":113,"props":281,"children":283},{"className":282},[],[284],{"type":52,"value":250},{"type":52,"value":286}," array, which\n",{"type":47,"tag":61,"props":288,"children":289},{},[290],{"type":52,"value":291},"replaces",{"type":52,"value":293}," the entire inline list, so always get the current experiment first via ",{"type":47,"tag":113,"props":295,"children":297},{"className":296},[],[298],{"type":52,"value":299},"experiment-get",{"type":52,"value":301},"\nto preserve existing metrics.",{"type":47,"tag":102,"props":303,"children":304},{},[305,310,312,318,320,324],{"type":47,"tag":61,"props":306,"children":307},{},[308],{"type":52,"value":309},"Shared (saved) metric",{"type":52,"value":311}," — a reusable metric object that can be attached to many experiments.\nAttached by ID via ",{"type":47,"tag":113,"props":313,"children":315},{"className":314},[],[316],{"type":52,"value":317},"saved_metrics_ids",{"type":52,"value":319}," (this list also ",{"type":47,"tag":61,"props":321,"children":322},{},[323],{"type":52,"value":291},{"type":52,"value":325}," the experiment's existing\nsaved-metric links, so resend the full set — see Step 1).",{"type":47,"tag":55,"props":327,"children":328},{},[329,334],{"type":47,"tag":61,"props":330,"children":331},{},[332],{"type":52,"value":333},"Prefer reusing a shared metric over duplicating it inline.",{"type":52,"value":335}," Build a new inline metric only when\nno suitable shared metric already exists.",{"type":47,"tag":86,"props":337,"children":339},{"id":338},"step-1-check-for-an-existing-shared-metric-required-match-by-definition-not-name",[340],{"type":52,"value":341},"Step 1: Check for an existing shared metric (REQUIRED — match by definition, not name)",{"type":47,"tag":55,"props":343,"children":344},{},[345],{"type":52,"value":346},"Before building any new inline metric, you MUST check whether the project already has a shared\n(saved) metric that measures the same thing, and reuse it. Duplicating a metric that already exists\nas a shared metric fragments measurement and is exactly what we want to avoid.",{"type":47,"tag":55,"props":348,"children":349},{},[350,363,365,371],{"type":47,"tag":61,"props":351,"children":352},{},[353,355,361],{"type":52,"value":354},"Reuse is decided by the metric ",{"type":47,"tag":356,"props":357,"children":358},"em",{},[359],{"type":52,"value":360},"definition",{"type":52,"value":362}," — the event or action plus the metric type — not the\nname.",{"type":52,"value":364}," Saved metrics are named by each team's own conventions, which you cannot guess, so you must\ncompare on what each metric measures (its ",{"type":47,"tag":113,"props":366,"children":368},{"className":367},[],[369],{"type":52,"value":370},"query",{"type":52,"value":372},"), never on its title.",{"type":47,"tag":55,"props":374,"children":375},{},[376],{"type":47,"tag":61,"props":377,"children":378},{},[379],{"type":52,"value":380},"Workflow:",{"type":47,"tag":98,"props":382,"children":383},{},[384,409,569,748],{"type":47,"tag":102,"props":385,"children":386},{},[387,392,394,400,402,407],{"type":47,"tag":61,"props":388,"children":389},{},[390],{"type":52,"value":391},"Know what you're about to build first.",{"type":52,"value":393}," Settle the target event(s)\u002Faction(s) and metric type\n(mean \u002F funnel \u002F ratio \u002F retention) before searching — see Step 2 to confirm the event exists via\n",{"type":47,"tag":113,"props":395,"children":397},{"className":396},[],[398],{"type":52,"value":399},"read-data-schema",{"type":52,"value":401},". You can only recognize a duplicate once you know the concrete event\u002Faction,\nso this check runs ",{"type":47,"tag":356,"props":403,"children":404},{},[405],{"type":52,"value":406},"after",{"type":52,"value":408}," you've pinned down the event, not before.",{"type":47,"tag":102,"props":410,"children":411},{},[412,423,425,431,433,439,441,447,449,454,456,464,466,472,474,480,482,487,489,500,502,508,510],{"type":47,"tag":61,"props":413,"children":414},{},[415,417,422],{"type":52,"value":416},"Search by the event, then compare each candidate's ",{"type":47,"tag":113,"props":418,"children":420},{"className":419},[],[421],{"type":52,"value":370},{"type":52,"value":201},{"type":52,"value":424}," Call ",{"type":47,"tag":113,"props":426,"children":428},{"className":427},[],[429],{"type":52,"value":430},"experiment-saved-metrics-list",{"type":52,"value":432},"\nwith ",{"type":47,"tag":113,"props":434,"children":436},{"className":435},[],[437],{"type":52,"value":438},"?event=\u003Cthe event you're measuring>",{"type":52,"value":440}," to find metrics that reference it — matched directly (an\n",{"type":47,"tag":113,"props":442,"children":444},{"className":443},[],[445],{"type":52,"value":446},"EventsNode",{"type":52,"value":448},") ",{"type":47,"tag":61,"props":450,"children":451},{},[452],{"type":52,"value":453},"or",{"type":52,"value":455}," via the step events of any action a metric references, so action-based metrics are\nfound by the event their action fires on. Then for each returned row, inspect its ",{"type":47,"tag":61,"props":457,"children":458},{},[459],{"type":47,"tag":113,"props":460,"children":462},{"className":461},[],[463],{"type":52,"value":370},{"type":52,"value":465}," (not the\n",{"type":47,"tag":113,"props":467,"children":469},{"className":468},[],[470],{"type":52,"value":471},"name",{"type":52,"value":473},"\u002F",{"type":47,"tag":113,"props":475,"children":477},{"className":476},[],[478],{"type":52,"value":479},"description",{"type":52,"value":481},"): a saved metric is a reuse match when its ",{"type":47,"tag":113,"props":483,"children":485},{"className":484},[],[486],{"type":52,"value":370},{"type":52,"value":488}," measures the ",{"type":47,"tag":61,"props":490,"children":491},{},[492,494],{"type":52,"value":493},"same event or\naction with the same ",{"type":47,"tag":113,"props":495,"children":497},{"className":496},[],[498],{"type":52,"value":499},"metric_type",{"type":52,"value":501}," (and compatible ",{"type":47,"tag":113,"props":503,"children":505},{"className":504},[],[506],{"type":52,"value":507},"math",{"type":52,"value":509},") as the metric you'd otherwise build, even\nif its name is different.\n",{"type":47,"tag":143,"props":511,"children":512},{},[513,523],{"type":47,"tag":102,"props":514,"children":515},{},[516,521],{"type":47,"tag":61,"props":517,"children":518},{},[519],{"type":52,"value":520},"Match on the event, not the action's name.",{"type":52,"value":522}," An action-based metric is discoverable by the event\nthe action fires on — pass that event, not the action's label.",{"type":47,"tag":102,"props":524,"children":525},{},[526,539,541,546,548,553,555,560,562,567],{"type":47,"tag":61,"props":527,"children":528},{},[529,531,537],{"type":52,"value":530},"Do not use ",{"type":47,"tag":113,"props":532,"children":534},{"className":533},[],[535],{"type":52,"value":536},"search",{"type":52,"value":538}," for this.",{"type":52,"value":540}," ",{"type":47,"tag":113,"props":542,"children":544},{"className":543},[],[545],{"type":52,"value":536},{"type":52,"value":547}," matches only the metric's own ",{"type":47,"tag":113,"props":549,"children":551},{"className":550},[],[552],{"type":52,"value":471},{"type":52,"value":554}," \u002F ",{"type":47,"tag":113,"props":556,"children":558},{"className":557},[],[559],{"type":52,"value":479},{"type":52,"value":561}," \u002F tags —\nnever the underlying event or action — so it cannot find a definition match. Use ",{"type":47,"tag":113,"props":563,"children":565},{"className":564},[],[566],{"type":52,"value":536},{"type":52,"value":568}," only when the\nuser names a specific saved metric to attach (name resolution, not a definition match).",{"type":47,"tag":102,"props":570,"children":571},{},[572,577,579],{"type":47,"tag":61,"props":573,"children":574},{},[575],{"type":52,"value":576},"If a saved metric matches the definition",{"type":52,"value":578}," — confirm the match with the user by name\u002Fdescription,\nthen attach it instead of building a new one:\n",{"type":47,"tag":143,"props":580,"children":581},{},[582,601,665,743],{"type":47,"tag":102,"props":583,"children":584},{},[585,587,592,594,600],{"type":52,"value":586},"Call ",{"type":47,"tag":113,"props":588,"children":590},{"className":589},[],[591],{"type":52,"value":299},{"type":52,"value":593}," to read the experiment's current ",{"type":47,"tag":113,"props":595,"children":597},{"className":596},[],[598],{"type":52,"value":599},"saved_metrics",{"type":52,"value":201},{"type":47,"tag":102,"props":602,"children":603},{},[604,605,610,612,617,619,623,625,631,633,639,641,647,649,655,657,663],{"type":52,"value":586},{"type":47,"tag":113,"props":606,"children":608},{"className":607},[],[609],{"type":52,"value":264},{"type":52,"value":611}," with ",{"type":47,"tag":113,"props":613,"children":615},{"className":614},[],[616],{"type":52,"value":317},{"type":52,"value":618}," set to the full desired set — it ",{"type":47,"tag":61,"props":620,"children":621},{},[622],{"type":52,"value":291},{"type":52,"value":624},"\nexisting links, so include the already-attached ones plus the new entry. Each entry has shape\n",{"type":47,"tag":113,"props":626,"children":628},{"className":627},[],[629],{"type":52,"value":630},"{ \"id\": \u003Csaved-metric id>, \"metadata\": { \"type\": \"primary\" } }",{"type":52,"value":632}," — set ",{"type":47,"tag":113,"props":634,"children":636},{"className":635},[],[637],{"type":52,"value":638},"type",{"type":52,"value":640}," to ",{"type":47,"tag":113,"props":642,"children":644},{"className":643},[],[645],{"type":52,"value":646},"\"primary\"",{"type":52,"value":648}," or\n",{"type":47,"tag":113,"props":650,"children":652},{"className":651},[],[653],{"type":52,"value":654},"\"secondary\"",{"type":52,"value":656},". ",{"type":47,"tag":113,"props":658,"children":660},{"className":659},[],[661],{"type":52,"value":662},"metadata",{"type":52,"value":664}," is optional and defaults to primary.",{"type":47,"tag":102,"props":666,"children":667},{},[668,673,675,680,682,688,690,695,697,703,705,710,712,717,719,727,729,734,736,741],{"type":47,"tag":61,"props":669,"children":670},{},[671],{"type":52,"value":672},"Watch the id when rebuilding the set:",{"type":52,"value":674}," each item in the ",{"type":47,"tag":113,"props":676,"children":678},{"className":677},[],[679],{"type":52,"value":599},{"type":52,"value":681}," you just read has a\ntop-level ",{"type":47,"tag":113,"props":683,"children":685},{"className":684},[],[686],{"type":52,"value":687},"id",{"type":52,"value":689}," (the ",{"type":47,"tag":356,"props":691,"children":692},{},[693],{"type":52,"value":694},"link",{"type":52,"value":696}," id) AND a ",{"type":47,"tag":113,"props":698,"children":700},{"className":699},[],[701],{"type":52,"value":702},"saved_metric",{"type":52,"value":704}," field (the ",{"type":47,"tag":356,"props":706,"children":707},{},[708],{"type":52,"value":709},"metric",{"type":52,"value":711}," id). ",{"type":47,"tag":113,"props":713,"children":715},{"className":714},[],[716],{"type":52,"value":317},{"type":52,"value":718},"\nwants the ",{"type":47,"tag":61,"props":720,"children":721},{},[722],{"type":47,"tag":113,"props":723,"children":725},{"className":724},[],[726],{"type":52,"value":702},{"type":52,"value":728}," value, not the link ",{"type":47,"tag":113,"props":730,"children":732},{"className":731},[],[733],{"type":52,"value":687},{"type":52,"value":735}," — sending the link ",{"type":47,"tag":113,"props":737,"children":739},{"className":738},[],[740],{"type":52,"value":687},{"type":52,"value":742}," attaches the wrong\nmetric or fails validation.",{"type":47,"tag":102,"props":744,"children":745},{},[746],{"type":52,"value":747},"You do not need to build the inline metric — the shared metric already encodes its events.",{"type":47,"tag":102,"props":749,"children":750},{},[751,756,758,764],{"type":47,"tag":61,"props":752,"children":753},{},[754],{"type":52,"value":755},"If nothing in the library measures the same event\u002Faction + type",{"type":52,"value":757}," — build an inline metric\n(Step 2+). When that inline metric is likely to be reused across experiments, offer to create it\nas a shared metric instead, via ",{"type":47,"tag":113,"props":759,"children":761},{"className":760},[],[762],{"type":52,"value":763},"experiment-saved-metrics-create",{"type":52,"value":765},", then attach it as above, so the\nnext experiment can reuse it.",{"type":47,"tag":86,"props":767,"children":769},{"id":768},"step-2-discover-available-events-required-before-building-an-inline-metric",[770],{"type":52,"value":771},"Step 2: Discover available events (REQUIRED before building an inline metric)",{"type":47,"tag":55,"props":773,"children":774},{},[775,777,782],{"type":52,"value":776},"Before suggesting or building any new inline metric, you MUST call ",{"type":47,"tag":113,"props":778,"children":780},{"className":779},[],[781],{"type":52,"value":399},{"type":52,"value":783}," to discover\nwhat events actually exist in the project. Do NOT skip this step. Do NOT suggest event names\nbased on what you think the project might track — only use events you have confirmed exist.\n(Attaching an existing shared metric from Step 1 does not need this — it already encodes its events.)",{"type":47,"tag":55,"props":785,"children":786},{},[787],{"type":52,"value":788},"This applies even when:",{"type":47,"tag":143,"props":790,"children":791},{},[792,797,802],{"type":47,"tag":102,"props":793,"children":794},{},[795],{"type":52,"value":796},"The user provides event names — look them up to confirm they exist and are spelled correctly",{"type":47,"tag":102,"props":798,"children":799},{},[800],{"type":52,"value":801},"The user asks \"what metrics do you suggest?\" — look up events first, then suggest from real data",{"type":47,"tag":102,"props":803,"children":804},{},[805],{"type":52,"value":806},"The context makes certain events seem obvious — they may not exist or may be named differently",{"type":47,"tag":55,"props":808,"children":809},{},[810],{"type":47,"tag":61,"props":811,"children":812},{},[813],{"type":52,"value":380},{"type":47,"tag":98,"props":815,"children":816},{},[817,828,833,838],{"type":47,"tag":102,"props":818,"children":819},{},[820,821,826],{"type":52,"value":586},{"type":47,"tag":113,"props":822,"children":824},{"className":823},[],[825],{"type":52,"value":399},{"type":52,"value":827}," to get the project's events",{"type":47,"tag":102,"props":829,"children":830},{},[831],{"type":52,"value":832},"Present relevant events to the user based on the experiment's hypothesis",{"type":47,"tag":102,"props":834,"children":835},{},[836],{"type":52,"value":837},"User picks which events to use for metrics",{"type":47,"tag":102,"props":839,"children":840},{},[841],{"type":52,"value":842},"Configure metrics with those confirmed event names",{"type":47,"tag":55,"props":844,"children":845},{},[846,858,860,866,867,872],{"type":47,"tag":61,"props":847,"children":848},{},[849,851,857],{"type":52,"value":850},"Legitimate exception — ",{"type":47,"tag":113,"props":852,"children":854},{"className":853},[],[855],{"type":52,"value":856},"allow_unknown_events: true",{"type":52,"value":266},{"type":52,"value":859},"\nPass this on ",{"type":47,"tag":113,"props":861,"children":863},{"className":862},[],[864],{"type":52,"value":865},"experiment-create",{"type":52,"value":554},{"type":47,"tag":113,"props":868,"children":870},{"className":869},[],[871],{"type":52,"value":264},{"type":52,"value":873}," only when the user is intentionally instrumenting an event that hasn't been ingested yet (e.g. setting up the experiment before the code change ships). Confirm this with the user — never use it as a workaround for \"the event lookup didn't return what I expected\".",{"type":47,"tag":55,"props":875,"children":876},{},[877],{"type":47,"tag":61,"props":878,"children":879},{},[880],{"type":52,"value":881},"Example:",{"type":47,"tag":883,"props":884,"children":889},"pre",{"className":885,"code":887,"language":52,"meta":888},[886],"language-text","User: \"Let's add some metrics for the checkout experiment\"\n\nWRONG: \"I'd suggest using purchase_completed as the primary metric...\"\n  (hallucinated event name — never seen the project's actual events)\n\nRIGHT: *calls read-data-schema* → \"Here are the events in your project\n  related to checkout: `checkout_step_completed`, `payment_processed`,\n  `order_confirmed`. Which of these represents a successful checkout?\"\n","",[890],{"type":47,"tag":113,"props":891,"children":892},{"__ignoreMap":888},[893],{"type":52,"value":887},{"type":47,"tag":86,"props":895,"children":897},{"id":896},"step-3-choose-metric-type",[898],{"type":52,"value":899},"Step 3: Choose metric type",{"type":47,"tag":55,"props":901,"children":902},{},[903,905,911],{"type":52,"value":904},"There are four metric types. Each has ",{"type":47,"tag":113,"props":906,"children":908},{"className":907},[],[909],{"type":52,"value":910},"kind: \"ExperimentMetric\"",{"type":52,"value":266},{"type":47,"tag":913,"props":914,"children":915},"table",{},[916,939],{"type":47,"tag":917,"props":918,"children":919},"thead",{},[920],{"type":47,"tag":921,"props":922,"children":923},"tr",{},[924,929,934],{"type":47,"tag":925,"props":926,"children":927},"th",{},[928],{"type":52,"value":499},{"type":47,"tag":925,"props":930,"children":931},{},[932],{"type":52,"value":933},"When to use",{"type":47,"tag":925,"props":935,"children":936},{},[937],{"type":52,"value":938},"Required fields",{"type":47,"tag":940,"props":941,"children":942},"tbody",{},[943,970,998,1049],{"type":47,"tag":921,"props":944,"children":945},{},[946,956,961],{"type":47,"tag":947,"props":948,"children":949},"td",{},[950],{"type":47,"tag":113,"props":951,"children":953},{"className":952},[],[954],{"type":52,"value":955},"\"mean\"",{"type":47,"tag":947,"props":957,"children":958},{},[959],{"type":52,"value":960},"Average of a numeric property per user (revenue, session duration, pageviews per user)",{"type":47,"tag":947,"props":962,"children":963},{},[964],{"type":47,"tag":113,"props":965,"children":967},{"className":966},[],[968],{"type":52,"value":969},"source",{"type":47,"tag":921,"props":971,"children":972},{},[973,982,987],{"type":47,"tag":947,"props":974,"children":975},{},[976],{"type":47,"tag":113,"props":977,"children":979},{"className":978},[],[980],{"type":52,"value":981},"\"funnel\"",{"type":47,"tag":947,"props":983,"children":984},{},[985],{"type":52,"value":986},"Conversion rate from exposure through one or more ordered actions",{"type":47,"tag":947,"props":988,"children":989},{},[990,996],{"type":47,"tag":113,"props":991,"children":993},{"className":992},[],[994],{"type":52,"value":995},"series",{"type":52,"value":997}," (1 or more steps)",{"type":47,"tag":921,"props":999,"children":1000},{},[1001,1010,1015],{"type":47,"tag":947,"props":1002,"children":1003},{},[1004],{"type":47,"tag":113,"props":1005,"children":1007},{"className":1006},[],[1008],{"type":52,"value":1009},"\"ratio\"",{"type":47,"tag":947,"props":1011,"children":1012},{},[1013],{"type":52,"value":1014},"Rate of one event relative to another",{"type":47,"tag":947,"props":1016,"children":1017},{},[1018,1024,1026,1032,1033,1039,1041,1047],{"type":47,"tag":113,"props":1019,"children":1021},{"className":1020},[],[1022],{"type":52,"value":1023},"numerator",{"type":52,"value":1025},", ",{"type":47,"tag":113,"props":1027,"children":1029},{"className":1028},[],[1030],{"type":52,"value":1031},"denominator",{"type":52,"value":632},{"type":47,"tag":113,"props":1034,"children":1036},{"className":1035},[],[1037],{"type":52,"value":1038},"math: \"sum\"",{"type":52,"value":1040}," + ",{"type":47,"tag":113,"props":1042,"children":1044},{"className":1043},[],[1045],{"type":52,"value":1046},"math_property",{"type":52,"value":1048}," on a side to aggregate a property; filters never aggregate",{"type":47,"tag":921,"props":1050,"children":1051},{},[1052,1061,1066],{"type":47,"tag":947,"props":1053,"children":1054},{},[1055],{"type":47,"tag":113,"props":1056,"children":1058},{"className":1057},[],[1059],{"type":52,"value":1060},"\"retention\"",{"type":47,"tag":947,"props":1062,"children":1063},{},[1064],{"type":52,"value":1065},"Do users come back after exposure?",{"type":47,"tag":947,"props":1067,"children":1068},{},[1069,1075,1076,1082,1083,1089,1090,1096,1097,1103,1104],{"type":47,"tag":113,"props":1070,"children":1072},{"className":1071},[],[1073],{"type":52,"value":1074},"start_event",{"type":52,"value":1025},{"type":47,"tag":113,"props":1077,"children":1079},{"className":1078},[],[1080],{"type":52,"value":1081},"completion_event",{"type":52,"value":1025},{"type":47,"tag":113,"props":1084,"children":1086},{"className":1085},[],[1087],{"type":52,"value":1088},"retention_window_start",{"type":52,"value":1025},{"type":47,"tag":113,"props":1091,"children":1093},{"className":1092},[],[1094],{"type":52,"value":1095},"retention_window_end",{"type":52,"value":1025},{"type":47,"tag":113,"props":1098,"children":1100},{"className":1099},[],[1101],{"type":52,"value":1102},"retention_window_unit",{"type":52,"value":1025},{"type":47,"tag":113,"props":1105,"children":1107},{"className":1106},[],[1108],{"type":52,"value":1109},"start_handling",{"type":47,"tag":55,"props":1111,"children":1112},{},[1113],{"type":47,"tag":61,"props":1114,"children":1115},{},[1116],{"type":52,"value":1117},"Funnel metrics and the implicit exposure step",{"type":47,"tag":55,"props":1119,"children":1120},{},[1121,1123,1129,1131,1136,1138,1143],{"type":52,"value":1122},"Funnel metrics automatically prepend the experiment's exposure event as ",{"type":47,"tag":113,"props":1124,"children":1126},{"className":1125},[],[1127],{"type":52,"value":1128},"step_0",{"type":52,"value":1130},".\nSo a funnel with 1 step in ",{"type":47,"tag":113,"props":1132,"children":1134},{"className":1133},[],[1135],{"type":52,"value":995},{"type":52,"value":1137}," is a valid 2-step funnel: ",{"type":47,"tag":61,"props":1139,"children":1140},{},[1141],{"type":52,"value":1142},"exposure → action",{"type":52,"value":1144},".\nThis is the correct choice for measuring \"what percentage of exposed users did X?\"",{"type":47,"tag":55,"props":1146,"children":1147},{},[1148],{"type":52,"value":1149},"Examples:",{"type":47,"tag":143,"props":1151,"children":1152},{},[1153,1166,1179],{"type":47,"tag":102,"props":1154,"children":1155},{},[1156,1158,1164],{"type":52,"value":1157},"\"What % of exposed users reached \u002Flogin?\" → funnel with 1 step (",{"type":47,"tag":113,"props":1159,"children":1161},{"className":1160},[],[1162],{"type":52,"value":1163},"$pageview",{"type":52,"value":1165}," filtered to \u002Flogin)",{"type":47,"tag":102,"props":1167,"children":1168},{},[1169,1171,1177],{"type":52,"value":1170},"\"What % of exposed users completed checkout?\" → funnel with 1 step (",{"type":47,"tag":113,"props":1172,"children":1174},{"className":1173},[],[1175],{"type":52,"value":1176},"checkout_completed",{"type":52,"value":1178},")",{"type":47,"tag":102,"props":1180,"children":1181},{},[1182],{"type":52,"value":1183},"\"What % of exposed users went cart → checkout → purchase?\" → funnel with 3 steps",{"type":47,"tag":55,"props":1185,"children":1186},{},[1187],{"type":47,"tag":61,"props":1188,"children":1189},{},[1190],{"type":52,"value":1191},"Mean vs funnel for the same event",{"type":47,"tag":143,"props":1193,"children":1194},{},[1195,1205],{"type":47,"tag":102,"props":1196,"children":1197},{},[1198,1203],{"type":47,"tag":61,"props":1199,"children":1200},{},[1201],{"type":52,"value":1202},"Mean",{"type":52,"value":1204}," measures average count\u002Fvalue per user (e.g. \"pageviews per user\", \"revenue per user\").",{"type":47,"tag":102,"props":1206,"children":1207},{},[1208,1213],{"type":47,"tag":61,"props":1209,"children":1210},{},[1211],{"type":52,"value":1212},"Funnel",{"type":52,"value":1214}," measures conversion rate (e.g. \"% of exposed users who purchased\").",{"type":47,"tag":55,"props":1216,"children":1217},{},[1218],{"type":52,"value":1219},"Both can reference the same event — the difference is whether you care about count\u002Fmagnitude (mean) or yes\u002Fno conversion (funnel).",{"type":47,"tag":55,"props":1221,"children":1222},{},[1223],{"type":47,"tag":61,"props":1224,"children":1225},{},[1226],{"type":52,"value":1227},"Retention: same vs different start\u002Fcompletion event",{"type":47,"tag":55,"props":1229,"children":1230},{},[1231],{"type":52,"value":1232},"The retention window is measured from the start event, so the events you pick decide what's measured:\nThe start occurrence never counts as its own completion (only a distinct later event does), so both shapes are valid:",{"type":47,"tag":143,"props":1234,"children":1235},{},[1236,1246],{"type":47,"tag":102,"props":1237,"children":1238},{},[1239,1244],{"type":47,"tag":61,"props":1240,"children":1241},{},[1242],{"type":52,"value":1243},"Different",{"type":52,"value":1245}," start and completion events → conversion-style retention (\"did they reach the target action within the window?\").",{"type":47,"tag":102,"props":1247,"children":1248},{},[1249,1254,1256,1261,1263,1269,1271,1277,1279,1285,1287,1293],{"type":47,"tag":61,"props":1250,"children":1251},{},[1252],{"type":52,"value":1253},"Same",{"type":52,"value":1255}," event → repeat retention (\"did they fire it ",{"type":47,"tag":356,"props":1257,"children":1258},{},[1259],{"type":52,"value":1260},"again",{"type":52,"value":1262},"?\"). ",{"type":47,"tag":113,"props":1264,"children":1266},{"className":1265},[],[1267],{"type":52,"value":1268},"From 0",{"type":52,"value":1270}," counts a repeat from the same period onward (same-day repeats included); ",{"type":47,"tag":113,"props":1272,"children":1274},{"className":1273},[],[1275],{"type":52,"value":1276},"From ≥ 1",{"type":52,"value":1278}," requires an occurrence later. Use ",{"type":47,"tag":113,"props":1280,"children":1282},{"className":1281},[],[1283],{"type":52,"value":1284},"start_handling: \"first_seen\"",{"type":52,"value":1286},". When a user says \"retention of ",{"type":47,"tag":113,"props":1288,"children":1290},{"className":1289},[],[1291],{"type":52,"value":1292},"\u003Cevent>",{"type":52,"value":1294},"\" they usually mean repeat retention.",{"type":47,"tag":55,"props":1296,"children":1297},{},[1298,1300,1306,1308,1314,1316,1322,1324,1329,1330,1335,1337,1342,1343,1348],{"type":52,"value":1299},"See ",{"type":47,"tag":113,"props":1301,"children":1303},{"className":1302},[],[1304],{"type":52,"value":1305},"references\u002Fmetric-configuration.md",{"type":52,"value":1307}," for the full rendered ",{"type":47,"tag":113,"props":1309,"children":1311},{"className":1310},[],[1312],{"type":52,"value":1313},"ExperimentMetric",{"type":52,"value":1315}," schema (all four metric types, with required fields per type) plus WRONG\u002FRIGHT JSON pairs for the failure modes that come up most often (ratio with ",{"type":47,"tag":113,"props":1317,"children":1319},{"className":1318},[],[1320],{"type":52,"value":1321},"is_set",{"type":52,"value":1323}," filter instead of ",{"type":47,"tag":113,"props":1325,"children":1327},{"className":1326},[],[1328],{"type":52,"value":1038},{"type":52,"value":1040},{"type":47,"tag":113,"props":1331,"children":1333},{"className":1332},[],[1334],{"type":52,"value":1046},{"type":52,"value":1336},"; retention without ",{"type":47,"tag":113,"props":1338,"children":1340},{"className":1339},[],[1341],{"type":52,"value":1088},{"type":52,"value":554},{"type":47,"tag":113,"props":1344,"children":1346},{"className":1345},[],[1347],{"type":52,"value":1109},{"type":52,"value":1349},"). Read it before assembling a ratio or retention payload — the required fields are authoritative.",{"type":47,"tag":86,"props":1351,"children":1353},{"id":1352},"step-4-primary-vs-secondary",[1354],{"type":52,"value":1355},"Step 4: Primary vs secondary",{"type":47,"tag":143,"props":1357,"children":1358},{},[1359,1369],{"type":47,"tag":102,"props":1360,"children":1361},{},[1362,1367],{"type":47,"tag":61,"props":1363,"children":1364},{},[1365],{"type":52,"value":1366},"Primary metrics",{"type":52,"value":1368}," — the main success criteria for the experiment. These drive the ship\u002Fend decision.",{"type":47,"tag":102,"props":1370,"children":1371},{},[1372,1377],{"type":47,"tag":61,"props":1373,"children":1374},{},[1375],{"type":52,"value":1376},"Secondary metrics",{"type":52,"value":1378}," — additional measurements for context. Useful for guardrail metrics (e.g., ensuring a conversion improvement doesn't increase error rates).",{"type":47,"tag":74,"props":1380,"children":1382},{"id":1381},"interpreting-results",[1383],{"type":52,"value":1384},"Interpreting results",{"type":47,"tag":55,"props":1386,"children":1387},{},[1388,1389,1395],{"type":52,"value":1299},{"type":47,"tag":113,"props":1390,"children":1392},{"className":1391},[],[1393],{"type":52,"value":1394},"references\u002Finterpreting-results.md",{"type":52,"value":1396}," for guidance on reading experiment results, statistical significance, and when to ship vs end.",{"items":1398,"total":1514},[1399,1414,1432,1449,1466,1480,1498],{"slug":1400,"name":1400,"fn":1401,"description":1402,"org":1403,"tags":1404,"stars":26,"repoUrl":27,"updatedAt":1413},"analyzing-experiment-session-replays","analyze session replays for PostHog experiments","Analyze session replay patterns across experiment variants to understand user behavior differences. Use when the user wants to see how users interact with different experiment variants, identify usability issues, compare behavior patterns between control and test groups, or get qualitative insights to complement quantitative experiment results.",{"slug":8,"name":9,"logoUrl":10,"githubOrg":8},[1405,1406,1409,1410],{"name":21,"slug":22,"type":13},{"name":1407,"slug":1408,"type":13},"Design","design",{"name":9,"slug":8,"type":13},{"name":1411,"slug":1412,"type":13},"User Research","user-research","2026-04-06T18:44:38.291781",{"slug":1415,"name":1415,"fn":1416,"description":1417,"org":1418,"tags":1419,"stars":26,"repoUrl":27,"updatedAt":1431},"assessing-heatmaps","analyze page heatmaps and suggest improvements","Assesses what a page's heatmap is telling you and recommends concrete changes. Pulls click \u002F rageclick \u002F scroll-depth data for a URL, names the hot elements by cross-referencing autocapture events on the same page, and can create a saved heatmap the user opens in PostHog, then summarizes the behavior and proposes improvements.\nTRIGGER when: user asks what a heatmap shows, why people aren't clicking something, where users rage-click, how far they scroll, what to change on a page based on heatmap\u002Fclick data, or to 'analyze\u002Fassess\u002Freview the heatmap' for a URL.\nDO NOT TRIGGER when: the user only wants to create a saved heatmap screenshot with no analysis (use heatmaps-saved-create directly), or is asking about session replay in general (use investigating-replay).",{"slug":8,"name":9,"logoUrl":10,"githubOrg":8},[1420,1421,1424,1425,1428],{"name":21,"slug":22,"type":13},{"name":1422,"slug":1423,"type":13},"Frontend","frontend",{"name":9,"slug":8,"type":13},{"name":1426,"slug":1427,"type":13},"Product Management","product-management",{"name":1429,"slug":1430,"type":13},"UX Design","ux-design","2026-06-05T07:40:43.37798",{"slug":1433,"name":1433,"fn":1434,"description":1435,"org":1436,"tags":1437,"stars":26,"repoUrl":27,"updatedAt":1448},"auditing-experiments-flags","audit PostHog experiments and feature flags","Audit PostHog experiments and feature flags for configuration issues, staleness, and best-practice violations. Read when the user asks to audit, health-check, or review experiments or feature flags, check flag hygiene, or verify experiment setup.",{"slug":8,"name":9,"logoUrl":10,"githubOrg":8},[1438,1441,1444,1445],{"name":1439,"slug":1440,"type":13},"Audit","audit",{"name":1442,"slug":1443,"type":13},"Feature Flags","feature-flags",{"name":9,"slug":8,"type":13},{"name":1446,"slug":1447,"type":13},"QA","qa","2026-04-06T18:44:30.657553",{"slug":1450,"name":1450,"fn":1451,"description":1452,"org":1453,"tags":1454,"stars":26,"repoUrl":27,"updatedAt":1465},"authoring-scouts","author and edit PostHog Signals scouts","How to author, edit, and adapt PostHog Signals scouts — the scheduled agents that scan a project and write reports into the Signals inbox. Use when a user wants to customize a canonical scout for their own setup (narrow its scope, retune its thresholds, add disqualifiers), tweak a scout's schedule or dry-run posture, or write a brand-new scout from scratch for a specific use case (a custom event, a product surface no canonical scout covers), or steer a scout without editing it at all by leaving it a note. Covers the scout SKILL.md anatomy, the report contract, the dedupe + scratchpad-memory conventions, the scout-notes steering channel, the per-team skills-store path vs the canonical in-repo path, and the write-and-inspect test loop (with dry-run as an optional safety net). Trigger on \"write\u002Fedit\u002Fcustomize a signals scout\", \"new scout for X\", \"tune my scout schedule\", \"make a scout that watches \u003Cevent>\", \"leave a note for \u002F give feedback to a scout\", \"tell the scouts about X\".\n",{"slug":8,"name":9,"logoUrl":10,"githubOrg":8},[1455,1458,1461,1464],{"name":1456,"slug":1457,"type":13},"Agents","agents",{"name":1459,"slug":1460,"type":13},"Automation","automation",{"name":1462,"slug":1463,"type":13},"Observability","observability",{"name":9,"slug":8,"type":13},"2026-07-28T05:33:45.509154",{"slug":1467,"name":1467,"fn":1468,"description":1469,"org":1470,"tags":1471,"stars":26,"repoUrl":27,"updatedAt":1479},"building-a-dashboard","build and update PostHog dashboards","Build a new dashboard, or update an existing one, from a set of insights — the same job the in-app assistant does with its upsert-dashboard tool, but over MCP. Use when a user asks to create a dashboard, put several metrics\u002Fcharts together on one page, assemble a dashboard for a topic (product analytics, retention, revenue, activation, etc.), or add\u002Fremove\u002Freplace insights on a dashboard they already have. Covers deciding create vs update, reusing existing insights vs creating new ones, and using PostHog's vetted dashboard templates as reference for what a strong dashboard on a topic looks like.\n",{"slug":8,"name":9,"logoUrl":10,"githubOrg":8},[1472,1473,1476],{"name":21,"slug":22,"type":13},{"name":1474,"slug":1475,"type":13},"Dashboards","dashboards",{"name":1477,"slug":1478,"type":13},"MCP","mcp","2026-07-21T06:07:38.060598",{"slug":1481,"name":1481,"fn":1482,"description":1483,"org":1484,"tags":1485,"stars":26,"repoUrl":27,"updatedAt":1497},"checking-deploy-timing","correlate PostHog deployments with GitHub commits","Determine when a PostHog code change reached a given environment by reading the hidden GIT deploy annotations in the project and correlating them with the merge commit on GitHub. Use when PostHog staff ask \"when was X deployed\", \"is my change live in the US\u002FEU yet\", \"has my PR shipped\", \"did the fix roll out to prod-us\", or otherwise want to know whether\u002Fwhen a commit, PR, or feature went out to a region. Do not answer deploy-timing questions from event\u002Fdata volume alone — that only shows when data changed, not when code shipped.",{"slug":8,"name":9,"logoUrl":10,"githubOrg":8},[1486,1489,1492,1495,1496],{"name":1487,"slug":1488,"type":13},"Deployment","deployment",{"name":1490,"slug":1491,"type":13},"Git","git",{"name":1493,"slug":1494,"type":13},"GitHub","github",{"name":1462,"slug":1463,"type":13},{"name":9,"slug":8,"type":13},"2026-06-28T07:46:59.53536",{"slug":1499,"name":1499,"fn":1500,"description":1501,"org":1502,"tags":1503,"stars":26,"repoUrl":27,"updatedAt":1513},"choosing-trend-or-slope-view","visualize trends and growth over time","Clarify how to visualize change over a time range before building a trend. Use whenever the user asks how much something changed, grew, dropped, improved, or regressed between two points or periods — \"how much did X change from A to B\", \"before vs after\", \"start vs end\", \"week over week\", \"compare this month to last\", \"change over time\" — or mentions a \"slope chart\" \u002F \"slopegraph\". Two readings of \"change\" need different charts: the whole trend (a line, every interval) versus just the two endpoints (a slope, start vs end). Ask which they want, then render it. Not for choosing a saved insight ChartDisplayType in the insight editor.\n",{"slug":8,"name":9,"logoUrl":10,"githubOrg":8},[1504,1505,1508,1511,1512],{"name":21,"slug":22,"type":13},{"name":1506,"slug":1507,"type":13},"Charts","charts",{"name":1509,"slug":1510,"type":13},"Data Visualization","data-visualization",{"name":9,"slug":8,"type":13},{"name":15,"slug":16,"type":13},"2026-06-18T08:18:57.960157",56,{"items":1516,"total":1675},[1517,1532,1542,1555,1568,1583,1599,1612,1624,1639,1649,1665],{"slug":1518,"name":1518,"fn":1519,"description":1520,"org":1521,"tags":1522,"stars":1529,"repoUrl":1530,"updatedAt":1531},"analyzing-expensive-users","analyze expensive users in AI observability","Analyze the most expensive users in AI observability and explain why they cost so much. Use when the user asks about top spenders, expensive users, per-user LLM cost, user-level cost drivers, or patterns behind high AI observability spend.\n",{"slug":8,"name":9,"logoUrl":10,"githubOrg":8},[1523,1524,1527,1528],{"name":21,"slug":22,"type":13},{"name":1525,"slug":1526,"type":13},"Cost Optimization","cost-optimization",{"name":1462,"slug":1463,"type":13},{"name":9,"slug":8,"type":13},35568,"https:\u002F\u002Fgithub.com\u002FPostHog\u002Fposthog","2026-07-28T05:34:11.117757",{"slug":1533,"name":1533,"fn":1534,"description":1535,"org":1536,"tags":1537,"stars":1529,"repoUrl":1530,"updatedAt":1541},"auditing-endpoints","audit PostHog project endpoints","Audit every endpoint in a PostHog project for staleness, failed materialisations, and unused materialised versions. Use when the user asks \"what endpoints can I clean up?\", \"are any of my endpoints broken?\", \"which materialised versions are still being called?\", or wants a one-shot cleanup pass over the Endpoints product. Produces a prioritised report grouped by issue type, with recommended actions but does not modify anything without explicit confirmation.\n",{"slug":8,"name":9,"logoUrl":10,"githubOrg":8},[1538,1539,1540],{"name":21,"slug":22,"type":13},{"name":1439,"slug":1440,"type":13},{"name":9,"slug":8,"type":13},"2026-06-08T08:08:33.693989",{"slug":1543,"name":1543,"fn":1544,"description":1545,"org":1546,"tags":1547,"stars":1529,"repoUrl":1530,"updatedAt":1554},"auditing-warehouse-source-health","audit PostHog data warehouse source health","Audit the health of a PostHog project's data warehouse sources and syncs — find every broken or degraded source connection, sync schema, and webhook channel. Use when the user asks \"why are my imports failing?\", \"what's broken with my sources?\", \"why is my warehouse data stale?\", or wants a one-shot triage of source\u002Fsync health before deciding where to dig in. Produces a prioritized report grouped by severity, with recommended next steps. For materialized-view health use `auditing-warehouse-view-health`; for a single failing sync use `diagnosing-failed-warehouse-syncs`.\n",{"slug":8,"name":9,"logoUrl":10,"githubOrg":8},[1548,1549,1552,1553],{"name":1439,"slug":1440,"type":13},{"name":1550,"slug":1551,"type":13},"Data Warehouse","data-warehouse",{"name":1462,"slug":1463,"type":13},{"name":9,"slug":8,"type":13},"2026-06-18T08:22:57.67984",{"slug":1556,"name":1556,"fn":1557,"description":1558,"org":1559,"tags":1560,"stars":1529,"repoUrl":1530,"updatedAt":1567},"auditing-warehouse-view-health","audit PostHog materialized view health","Audit the health of a PostHog project's materialized views (saved queries) — find every failed materialization and flag unused or stale materialized views that cost storage and compute. Use when the user asks \"which of my views are broken?\", \"why is this materialized view failing?\", \"are any of my views wasting compute?\", or wants a one-shot triage of view health. For source\u002Fsync health use `auditing-warehouse-source-health`.\n",{"slug":8,"name":9,"logoUrl":10,"githubOrg":8},[1561,1562,1563,1566],{"name":1439,"slug":1440,"type":13},{"name":1550,"slug":1551,"type":13},{"name":1564,"slug":1565,"type":13},"Performance","performance",{"name":9,"slug":8,"type":13},"2026-06-18T08:25:10.936787",{"slug":1569,"name":1569,"fn":1570,"description":1571,"org":1572,"tags":1573,"stars":1529,"repoUrl":1530,"updatedAt":1582},"authoring-error-tracking-alerts","author PostHog error tracking alerts","Author error tracking alerts that fire when an issue is created, reopened, or starts spiking. Use when the user asks to set up error notifications, route exceptions to Slack\u002Fwebhook\u002FLinear, or evaluate which error events are worth alerting on. Covers trigger-event selection, integration choice, dedup against existing alerts, and shipping with the canonical message body shape.\n",{"slug":8,"name":9,"logoUrl":10,"githubOrg":8},[1574,1577,1580,1581],{"name":1575,"slug":1576,"type":13},"Alerting","alerting",{"name":1578,"slug":1579,"type":13},"Debugging","debugging",{"name":1462,"slug":1463,"type":13},{"name":9,"slug":8,"type":13},"2026-06-18T08:24:40.318583",{"slug":1584,"name":1584,"fn":1585,"description":1586,"org":1587,"tags":1588,"stars":1529,"repoUrl":1530,"updatedAt":1598},"authoring-log-alerts","author log alerts in PostHog","Author useful, low-noise log alerts on services in a PostHog project. Use when the user asks to set up alerts for their logs, suggest alerts they should add, or evaluate whether a service is worth monitoring. Covers service triage, baseline characterisation, threshold drafting, back-testing via simulate, and shipping with a notification destination.\n",{"slug":8,"name":9,"logoUrl":10,"githubOrg":8},[1589,1590,1593,1594,1597],{"name":21,"slug":22,"type":13},{"name":1591,"slug":1592,"type":13},"Monitoring","monitoring",{"name":1462,"slug":1463,"type":13},{"name":1595,"slug":1596,"type":13},"Operations","operations",{"name":9,"slug":8,"type":13},"2026-07-18T05:10:54.430898",{"slug":1600,"name":1600,"fn":1601,"description":1602,"org":1603,"tags":1604,"stars":1529,"repoUrl":1530,"updatedAt":1611},"building-workflows","build and edit PostHog workflows","Build, edit, test, enable, and monitor PostHog workflows over MCP. Author the action\u002Fedge graph so it runs and opens cleanly in the visual editor, then change drafts surgically with patch operations. Use when asked to build, set up, automate, change, fix, or debug a workflow, campaign, broadcast, drip sequence, or event-triggered automation in the workflows product.",{"slug":8,"name":9,"logoUrl":10,"githubOrg":8},[1605,1606,1607,1608],{"name":1459,"slug":1460,"type":13},{"name":1477,"slug":1478,"type":13},{"name":9,"slug":8,"type":13},{"name":1609,"slug":1610,"type":13},"Workflow Automation","workflow-automation","2026-07-28T05:34:12.167015",{"slug":1613,"name":1613,"fn":1614,"description":1615,"org":1616,"tags":1617,"stars":1529,"repoUrl":1530,"updatedAt":1623},"check-posthog-loading","inspect PostHog SDK loading across URLs","Inspect how the PostHog JavaScript SDK is loaded across a list of URLs. Use to confirm consistent installation across pages, find pages missing the snippet, detect mismatched API keys or hosts between pages, and verify the load method (head snippet vs deferred vs array.js).\n",{"slug":8,"name":9,"logoUrl":10,"githubOrg":8},[1618,1619,1620,1621,1622],{"name":21,"slug":22,"type":13},{"name":1578,"slug":1579,"type":13},{"name":1422,"slug":1423,"type":13},{"name":1462,"slug":1463,"type":13},{"name":9,"slug":8,"type":13},"2026-05-07T05:56:19.828048",{"slug":1625,"name":1625,"fn":1626,"description":1627,"org":1628,"tags":1629,"stars":1529,"repoUrl":1530,"updatedAt":1638},"consuming-endpoints-from-client-code","integrate PostHog endpoints into client applications","Wire a PostHog endpoint into a client app or SDK. Covers fetching the OpenAPI spec, generating a typed client with openapi-generator or @hey-api\u002Fopenapi-ts, sending the right auth header, shaping the variables payload (HogQL code_name vs insight breakdown property), handling rate-limit and materialised-endpoint error responses. Use when the user says \"how do I call my endpoint\", \"generate a client for this\", or \"what auth header do I use\".\n",{"slug":8,"name":9,"logoUrl":10,"githubOrg":8},[1630,1633,1634,1635],{"name":1631,"slug":1632,"type":13},"API Development","api-development",{"name":1422,"slug":1423,"type":13},{"name":9,"slug":8,"type":13},{"name":1636,"slug":1637,"type":13},"SDK","sdk","2026-06-08T08:08:34.929454",{"slug":1640,"name":1640,"fn":1641,"description":1642,"org":1643,"tags":1644,"stars":1529,"repoUrl":1530,"updatedAt":1648},"copying-endpoints-across-projects","copy PostHog endpoints across projects","Copy a PostHog endpoint (a saved HogQL\u002Finsight query exposed as an API route) to another project in the same organization, or duplicate it under a new name in the same project. Use when the user wants to duplicate an endpoint, promote an endpoint from staging to production, replicate an endpoint's query\u002Fvariables\u002Ffreshness config in another workspace, or clone an endpoint to iterate on it. Unlike feature flags and experiments, endpoints have NO native cross-project copy tool — this skill covers the read-then-recreate flow (endpoint-get then endpoint-create), the active-project switching it requires, name-collision checks, and the safe defaults (land unmaterialised in the target, verify with endpoint-run). Does not cover editing endpoint versions (see managing-endpoint-versions) or authoring a brand-new endpoint from scratch (see creating-an-endpoint).\n",{"slug":8,"name":9,"logoUrl":10,"githubOrg":8},[1645,1646,1647],{"name":1631,"slug":1632,"type":13},{"name":1595,"slug":1596,"type":13},{"name":9,"slug":8,"type":13},"2026-07-15T05:29:58.442727",{"slug":1650,"name":1650,"fn":1651,"description":1652,"org":1653,"tags":1654,"stars":1529,"repoUrl":1530,"updatedAt":1664},"creating-ai-subscription","schedule recurring AI-generated PostHog reports","Create a recurring AI-generated PostHog report — schedule a free-text prompt to run on a cron, with the LLM-synthesized markdown delivered to email or Slack on each tick. Use when the user wants a recurring AI summary of X on any cadence (daily, weekly, monthly, yearly) rather than a one-off report. (To attach an AI summary to an existing insight\u002Fdashboard subscription instead of a free-text prompt, see `managing-subscriptions` and its `summary_enabled` option.)\n",{"slug":8,"name":9,"logoUrl":10,"githubOrg":8},[1655,1656,1659,1660,1661],{"name":1459,"slug":1460,"type":13},{"name":1657,"slug":1658,"type":13},"Email","email",{"name":9,"slug":8,"type":13},{"name":15,"slug":16,"type":13},{"name":1662,"slug":1663,"type":13},"Slack","slack","2026-06-09T07:32:27.935712",{"slug":1666,"name":1666,"fn":1667,"description":1668,"org":1669,"tags":1670,"stars":1529,"repoUrl":1530,"updatedAt":1674},"creating-an-endpoint","create PostHog API endpoints","Create a PostHog endpoint with the right shape on the first try — covers query kind choice, name conventions, what to expose as variables (HogQL code_name vs insight breakdown), data_freshness_seconds, and whether to materialise on day one. Use when the user says \"create an endpoint\", \"expose this query as an API\", \"turn this insight into an endpoint\", or asks for help structuring a new endpoint. Steers away from common mistakes: materialising a query with cohort breakdowns or compare mode, inline-only variables on a materialised endpoint, unbounded date ranges, ambiguous names.\n",{"slug":8,"name":9,"logoUrl":10,"githubOrg":8},[1671,1672,1673],{"name":21,"slug":22,"type":13},{"name":1631,"slug":1632,"type":13},{"name":9,"slug":8,"type":13},"2026-06-08T08:08:29.624498",231]