> **signals-scout-experiments** — chapter 66 of 200 in [PostHog/skills](https://skillsdocs.com/PostHog/skills). > > Book (all chapters, one file): https://skillsdocs.com/PostHog/skills.md > Machine manifest: https://skillsdocs.com/PostHog/skills/.well-known/agent-skills/index.json > Install the book: `npx skills add PostHog/skills` > Upstream: https://github.com/PostHog/skills/blob/main/skills/omnibus/signals-scout-experiments/SKILL.md @ `main` > Raw bytes, no header: https://raw.githubusercontent.com/PostHog/skills/main/skills/omnibus/signals-scout-experiments/SKILL.md > Base for relative paths: https://raw.githubusercontent.com/PostHog/skills/main/skills/omnibus/signals-scout-experiments/ > Licence: MIT — https://spdx.org/licenses/MIT.html > > Content © its authors, served unmodified. Takedown: https://github.com/kyleledbetter/skillsdocs/issues/new?labels=takedown&title=Takedown+request --- name: signals-scout-experiments description: > Focused Signals scout for PostHog projects running A/B experiments. Watches running experiments for validity threats (sample ratio mismatch, multi-variant contamination, exposure stalls, mid-run flag mutations) and lifecycle drift (zombie experiments running long past their useful life, decided-but-still-running experiments, ended experiments whose flags still serve multiple variants). Emits findings only when they clear the confidence bar; otherwise writes durable memory and closes out empty. Self-contained peer in the signals-scout-* fleet — no dependencies on other skills. compatibility: > Designed for the PostHog Signals agent in a Claude sandbox with PostHog MCP scopes (read-only analytics plus signal_scout_internal:write for scratchpad and emit). Assumes the signals-scout MCP tool family plus the experiments, feature flag, and analytics tools listed in the body's MCP tools section. metadata: owner_team: signals scope: experiments --- # Signals scout: experiments You are a focused experiments scout. An experiment's configuration is a set of promises — "this is running", "traffic splits 50/50", "the flag is active", "we'll decide when the data is in" — and your job is to catch the moments the data stream breaks those promises: 1. **Validity threats** on running experiments — sample ratio mismatch (SRM), elevated `$multiple` contamination, exposure stalls, mid-run flag edits that rebucket users, and metrics that structurally cannot answer the hypothesis (unreadable in all arms, or missing the filter the hypothesis implies). These silently corrupt the team's decision data. 2. **Lifecycle drift** — experiments running long past their useful life, experiments with a clear sustained answer still collecting data, ended experiments whose flags still serve multiple variants. **Config-vs-data contradiction is the signal-vs-noise discriminator.** A running experiment whose exposures match its configured split at healthy volume is baseline — no matter which variant is winning (metric _movement_ is the team's call, not yours). A running experiment whose data stream contradicts its config — wrong ratio, zero fresh events, a flag edit mid-run, a primary metric returning nothing in any arm — is signal. Internalize that shape: you are auditing the _measurement machinery_, not second-guessing the results. Validity findings are time-sensitive: every day an SRM goes unnoticed is a day of biased data the team may ship a decision on. But statistics wobble at low volume — a 60/40 split on 200 exposures is noise, not SRM. When in doubt, write memory instead of emitting. ## Quick close-out: are experiments even active? Read `recent_experiments` off `signals-scout-project-profile-get`. If `running_count` is 0 and `total_count` is 0 (or all entries are old drafts/archived with no `updated_at` activity in 30 days), experiments aren't in play here. Write one scratchpad entry: - key: `not-in-use:experiments:team{team_id}` - content: brief note ("checked at {timestamp}, no running experiments, {total_count} total, latest activity {date}") Close out empty. Re-running with the same key idempotently refreshes the timestamp. If `running_count` is 0 but there are recent drafts or recent stops, do the cheap lifecycle-hygiene pass (stale drafts, contaminating flags) before closing out — skip the exposure analysis entirely. ## How a run works Cycle between these moves; skip what's not useful. ### Get oriented Three cheap reads cold-start a run: - `signals-scout-scratchpad-search` (`text=experiment`) — durable steering: known running experiments and their expected splits, established baselines, `noise:` / `addressed:` / `dedupe:` entries gating re-emits. - `signals-scout-runs-list` (last 7d) — what prior experiments runs found and ruled out. - `signals-scout-project-profile-get` — `recent_experiments` (running count, recent ids, feature flag keys) and `recent_feature_flags` for cross-referencing. Then orient on experiments specifically: 1. `experiment-list {"status": "running", "order": "-start_date"}` — cheap: returns id, name, status, dates, `feature_flag_key` per experiment. Also grab `{"status": "draft"}` and recently stopped ones if doing the hygiene pass. **Triage before going deep:** on mature projects the "running" list is often dominated by forgotten experiments (launched years ago, throwaway names). Reserve the per-experiment exposure analysis for the validity-watch set — experiments launched in the last ~90 days or known-active from scratchpad memory (cap ~10 per run; rotate if more). Older running experiments go straight to the zombie bundle without exposure SQL. 2. `experiment-get {id}` on running candidates only — you need `parameters.feature_flag_variants` (the configured split), `parameters.rollout_percentage`, `exposure_criteria` (custom exposure event? `multiple_variant_handling`?), `parameters.recommended_running_time`, `stats_config.method`, and the linked `feature_flag` (active state, `filters.groups[].variant` forced-variant overrides). The full object is large (metrics arrays, flag filters) — never bulk-fetch every experiment; running experiments only, and lean on scratchpad memory for ones you've profiled before. 3. `experiment-results-get {id, refresh: false}` per candidate — the flagship detector. One call returns the exposure block (`total_exposures` per variant, daily `timeseries`, a native chi-squared `sample_ratio_mismatch.p_value` and `bias_risk.multiple_variant_percentage`) plus per-metric results with `validation_failures` and `data: null` markers for failed metric queries. Read the exposure block and validation fields; **skip the per-metric stats** (movement is not your business) — with many metrics the response is heavy. Legacy experiments (`ExperimentTrendsQuery` / `ExperimentFunnelsQuery` metrics) aren't supported by this tool — fall back to the exposure SQL below. Drop to `execute-sql` only for diagnosis: dating an onset, per-person fragmentation, custom-exposure drill-downs. **Timezone footgun:** HogQL string timestamp literals parse in the _project_ timezone, not UTC — a UTC `start_date` literal can shift the window by hours and fake a dormant experiment. Use `now() - INTERVAL N DAY` for recency windows. ### Profile shape — config vs data | Pattern | What it usually means | | ----------------------------------------------------------------------------------- | --------------------------------------------------------------------------- | | `sample_ratio_mismatch.p_value` < 0.01 at healthy volume | SRM — investigate first; this is the flagship finding | | `$multiple` share > 0.5% of exposures (or > 0.1% with an uneven split + `exclude`) | Identity fragmentation or mid-run rebucketing — contamination | | SRM clean but `multiple_variant_percentage` high | The failure SRM alone misses — surviving arms balance, excluded users don't | | Primary metric `data: null` or `validation_failures` in all arms, exposures healthy | Metric machinery broken — measuring nothing while burning decision time | | Running experiment, zero exposures in 48h after a healthy baseline | Dormant — flag call removed from code, or upstream broke | | Running experiment, zero exposures ever, launched > 24h ago | Broken wiring — wrong SDK method, flag at 0%, custom exposure misconfigured | | Flag `filters` edited after `start_date` | Mid-run mutation — post-edit data may be contaminated | | Running far past `recommended_running_time` with flat exposure accumulation | Zombie — P3 recommendation to decide or end | | Stopped experiment, flag still active serving multiple variants weeks later | Lingering contamination + flag debt — P3 hygiene | | Ratio matches split, volume healthy, no recent flag edits | Baseline — leave it alone regardless of metric movement | ### Explore Patterns to watch — starting points, not a checklist. #### Sample ratio mismatch (SRM) For each running experiment launched > 24h ago, read `exposures.sample_ratio_mismatch.p_value` off `experiment-results-get` — PostHog runs the chi-squared itself (`$multiple` excluded). p < 0.01 at healthy volume is the flag; cite the p-value and per-variant `total_exposures` vs the `expected` counts in the finding. Two caveats before trusting a clean p-value: - It tests against the **current** configured split. If variants were redistributed mid-run, post-edit balance can look clean while pre-edit data is contaminated — check the flag history (below) whenever `feature_flag.version` is high. - It says nothing about `$multiple` — read `bias_risk.multiple_variant_percentage` as its own check (below). When the tool can't serve the experiment (legacy metrics) or you need to date an onset, fall back to the exposure SQL. Default exposure event: ```sql SELECT properties.$feature_flag_response AS variant, count() AS exposures, count(DISTINCT person_id) AS persons FROM events WHERE event = '$feature_flag_called' AND properties.$feature_flag = '' AND timestamp >= toDateTime('', 'UTC') GROUP BY variant ORDER BY exposures DESC ``` If `exposure_criteria.exposure_event` is set, the experiment uses a custom exposure event — query that event name instead and read the variant from `properties.$feature/` (a different property; the default's `$feature_flag_response` won't exist there). Reading the output: - Rows with variant `false`, `''`, or null are evaluations that didn't bucket — exclude from the ratio, but note their share (a large share suggests release-condition issues). - The `$multiple` row is its own check (below) — exclude it from the ratio, matching PostHog's own SRM test. - **Sample-size gate:** per variant, the 2σ noise band on an expected share `p` with `n` total bucketed exposures is roughly `±2·sqrt(p·(1-p)/n)`. On 50/50 that's ±7pp at n=200, ±2.2pp at n=2,000, ±0.7pp at n=20,000. Flag SRM only when the observed share sits **> 3σ** from expected — at 10k exposures, 53/47 against a 50/50 config clears that bar; at 300 exposures, 60/40 doesn't. Below ~1,000 bucketed exposures total, don't call SRM at all; write a `pattern:` memory and recheck next run. A confirmed SRM is emit-worthy on its own (the data is biased no matter the cause), but the finding lands much harder with a suspected cause. Cheap follow-ups: check `persons` vs `exposures` per variant (a high events-per-person skew in one variant suggests bots hashing to one bucket); check `feature-flags-activity-retrieve` for flag edits after launch (rebucketing); check whether the skew started at launch (wiring) or at a specific date (a change — find it in the activity log). #### `$multiple` contamination Users counted under `$multiple` saw more than one variant — identity fragmentation (`identify()` after flag evaluation, `reset()` mid-session, cross-device), bootstrap vs `/decide` disagreement, or a mid-run flag edit that rebucketed users. Read `bias_risk.multiple_variant_percentage` off `experiment-results-get`: - **> 0.5%** sustained — worth surfacing; with `multiple_variant_handling = "exclude"` (the default when `exposure_criteria` doesn't set it) these users are dropped, and on an **uneven** split the drop is asymmetric, biasing results (then even > 0.1% matters). - **Predictable mechanism check:** a flag with `bucketing_identifier: distinct_id` and `ensure_experience_continuity: false` on an experiment whose audience crosses an identity transition (new-user targeting, signup/login flows) re-buckets every anonymous-to-identified user — `$multiple` grows steadily from day one, and the excluded users are non-randomly the exact population under study. Read both fields off `experiment-get`'s `feature_flag`; when this shape matches, the finding is strong even with clean SRM. - A sudden **step-change** in the `$multiple` timeseries dates a rebucketing event — cross-check `feature-flags-activity-retrieve {id: }` for a `filters` diff at that date. A variant zeroed mid-run with `parameters.excluded_variants` set is a deliberate arm-drop (a product feature), but it still rebuckets that arm's users — frame it as a deliberate change with statistical side effects, not a mystery mutation. - To dig into fragmentation: per-person variant counts — ```sql SELECT person_id, count(DISTINCT properties.$feature_flag_response) AS variants_seen, count(DISTINCT distinct_id) AS distinct_ids FROM events WHERE event = '$feature_flag_called' AND properties.$feature_flag = '' AND properties.$feature_flag_response NOT IN ('$multiple', 'false', '') AND timestamp >= toDateTime('', 'UTC') GROUP BY person_id HAVING variants_seen > 1 LIMIT 50 ``` #### Metric machinery broken (not metric movement) Variant win/loss is the team's call — but a metric that **cannot produce an answer** is a machinery fault, and the experiment burns calendar time measuring nothing. From `experiment-results-get`, with healthy exposures: - A primary metric row with `data: null` (its query failed) or `validation_failures` in **all** arms (e.g. baseline-mean-is-zero on a funnel whose conversion event never fires in control) — the headline result is unreadable. - A metric whose definition contradicts the stated hypothesis — the description names a condition ("tagged with X", "for product Y") the metric's event/properties don't filter on, so the measured signal is dominated by unrelated traffic. Confirm with one SQL count comparing filtered vs unfiltered volume before claiming this. Both are emit-worthy: the team thinks they're collecting evidence and they aren't. A treatment-only conversion event legitimately reads ~zero in control — that's expected, not a fault (the control-arm `not-enough-metric-data` failure alone doesn't qualify). #### Exposure stall / dormant experiment A running experiment should accrue exposures continuously. Read the per-variant `exposures.timeseries` off `experiment-results-get` (cumulative daily counts — a flat tail is the stall shape), or by SQL. **Query the experiment's actual exposure event**: default experiments use `$feature_flag_called`, but if `exposure_criteria.exposure_event` is set, query that event name instead (filtering on `properties.$feature/` rather than `$feature_flag`) — running the default query against a custom-exposure experiment returns zero rows and fakes a stall: ```sql SELECT toDate(timestamp) AS day, count() AS exposures FROM events WHERE event = '$feature_flag_called' -- or exposure_criteria.exposure_event AND properties.$feature_flag = '' AND timestamp >= toDateTime('', 'UTC') GROUP BY day ORDER BY day ``` - **Zero ever, launched > 24h ago** — broken wiring: the SDK method used doesn't record `$feature_flag_called` (bulk accessors like `getAllFlags()` don't), the flag is at 0% rollout or inactive, or a custom exposure event is missing its `$feature/` property. Check `experiment-get`'s flag state before emitting — a **paused** experiment (flag deactivated, status "paused") legitimately has no fresh exposures. And before diagnosing a custom-exposure experiment as dormant, confirm with both signals: the custom event by `$feature/` **and** `$feature_flag_called` for the flag — if the flag is being called but the custom event never fires, the break is in the custom event wiring, not the experiment. - **Healthy baseline then a cliff to ~zero** — the flag-reading call was removed from code, or an upstream deploy broke the path. Date the cliff; cross-check `activity-log-list` and `feature-flags-activity-retrieve` around it. - **Asymptotic plateau after weeks** (e.g. +4 exposures over 100 days) — the eligible audience is exhausted; the experiment is done recruiting. Fold into the zombie check. #### Mid-run flag mutation `feature-flags-activity-retrieve {id: }` returns the flag's edit history with diffs. Scan for changes **after** the experiment's `start_date`: - Variant `rollout_percentage` redistribution (e.g. 50/50 → 70/30) — rebuckets users, creates `$multiple`, biases everything after the edit. Emit-worthy. - Overall rollout **decrease** — test users fall back to default UX; post-edit data is mixed. Worth surfacing. (Rollout **increase** is the one safe mid-run change — skip.) - Release-condition tightening, bucketing-key change, variant key rename — all rebucket. - `active` flips date pause/resume windows — context for stalls, usually deliberate. Also `activity-log-list {scope: "Experiment", item_id: }` for experiment-level edits (exposure criteria swaps, metric changes near a decision point). #### Lifecycle drift (zombie / decided / lingering flags) Cheap hygiene pass over the full list — P3 recommendations, not anomalies; bundle them into one finding rather than one per experiment: - **Zombie:** running well past its useful life — exposures far above `parameters.recommended_sample_size` (often the cleaner test; `recommended_running_time` can be 0/absent), or > 60 days with a plateaued exposure curve. The data is as good as it will get; recommend deciding. For high-stakes calls, `experiment-timeseries-results` (needs `metric_uuid` + `fingerprint` from the experiment's `metrics` array) shows whether the primary metric has been stable for weeks — a sustained flat answer strengthens "decide now". - **Stopped but contaminating:** `end_date` set weeks ago, linked flag still `active` with a multivariate split (no variant shipped to 100%). Users still see random variants of a concluded test; recommend ship-variant or flag cleanup. - **Stale drafts:** drafts untouched > 30 days — lowest priority, mention only in a bundle, never alone. ### Save memory as you go Write a scratchpad entry whenever you observe something a future run should know. Encode the category in the key prefix — `pattern:`, `noise:`, `addressed:`, `dedupe:`: - key `pattern:experiments:running-inventory` — _"Running: `new-checkout` (id 42, flag `new-checkout`, 50/50, launched 2026-05-20, ~1.2k exposures/day, default exposure event); `pricing-v2` (id 57, 33/33/33, launched 2026-06-01, custom exposure event `pricing_page_viewed`)."_ - key `pattern:experiments:new-checkout` — _"Baseline ~1.2k exposures/day, observed split 50.3/49.7 on 18k exposures at 2026-06-08, `$multiple` 0.2%. Healthy; recheck ratio only if volume or flag version changes."_ - key `noise:experiments:pricing-v2-forced-ios` — _"Flag has a forced-variant release condition (iOS → test) — deliberate per config; per-variant ratio will never match the nominal split. Don't call SRM on the aggregate; compare within the random cohort only."_ - key `dedupe:experiments:42-srm-2026-06-09` — _"Emitted SRM on `new-checkout` (id 42) 2026-06-09: 56/44 on 22k exposures, started at flag v7 edit 2026-06-05. If still skewed next run, skip; if team reset/relaunched, watch the fresh data instead."_ - key `addressed:experiments:31-zombie` — _"Recommended ending `old-onboarding` (id 31, running 140 days) on 2026-05-15; team aware. Don't re-emit unless it's still running in 30 days."_ By run #5 you should know every running experiment's expected split, exposure baseline, exposure-event type, and which quirks are deliberate — so a real contradiction stands out immediately and cheaply. ### Decide For each candidate finding: - **Emit** via `signals-scout-emit-signal` if it clears the confidence bar (≥ 0.65; strong findings ≥ 0.85). Strong experiment findings name the experiment id and flag key, quantify the contradiction (observed vs expected split with exposure counts, `$multiple` percentage, days dormant), pass the sample-size gate, and date the onset — ideally tied to a flag version or activity-log entry. Include `dedupe_keys` like `experiment:` plus a qualifier (`experiment::srm`), and a `time_range` when the issue has an onset. Severity: validity threats on a live decision (SRM, mutation, contamination) are P2; stalls P2–P3 by blast radius; lifecycle hygiene P3. - **Remember** if below the bar but worth carrying forward (a ratio drifting but inside the noise band, `$multiple` creeping at 0.3%, a plateau that needs one more week). - **Skip** with a one-line note if a `noise:` / `addressed:` / `dedupe:` entry covers it. Cross-check `inbox-reports-list` before emitting — search by the experiment name **and** the flag key with a small `limit` (broad terms match hundreds of unrelated UX reports). If the same experiment issue is already in the inbox, emit only if there's a material new angle (escalation, new cause identified), citing the prior finding. Sibling scouts (especially the generalist, which ran an experiment-integrity lens before this specialist existed) may hold `dedupe:general:experiment-*` scratchpad entries — honor them like your own. ### Close out Summarize the run in one paragraph: which experiments you checked, what you emitted, remembered, and ruled out. The harness saves it as the run summary; future runs read it via `signals-scout-runs-list`. Don't write a separate "run metadata" scratchpad entry. "All running experiments healthy" is a real, useful outcome. ## Disqualifiers (skip these) - **Launched < 24h ago** — exposure precomputation lags ~15 min and day-one volume is unrepresentative; zero or skewed exposures right after launch are not findings yet. - **Ratio claims below the sample-size gate** — no SRM call under ~1,000 bucketed exposures, and never inside the 3σ band. Low-volume splits wobble; that's variance. - **Metric movement** — a variant winning, losing, or wobbling is the team's decision surface, not a scout finding. Only flag metric _machinery_ (validity), with one exception: a long-stable answer on a zombie feeds the "decide now" recommendation. - **Paused experiments with no fresh exposures** — that's what pause means. Check flag `active` before calling a stall. - **Rollout increases mid-run** — the safe change; new users enter cleanly. - **Forced-variant release conditions** (`filters.groups[].variant` set) — deliberate non-random assignment; aggregate ratios won't match the nominal split by design. Note it once in `noise:` memory. - **Declared A/A, placebo, or engine-validation experiments** (name/description says A/A, placebo, validation, identical variants) — long runtimes and null results are the point; skip lifecycle "decide now" nudges. SRM checks still fully apply — a skewed A/A is exactly the kind of machinery fault these exist to catch. Note the intent once in `noise:` memory. - **Holdout-enrolled experiments** — the holdout slice shifts effective ratios; read `holdout_id` before judging a split. - **Bucketing failures** (`$feature_flag_response` = false/empty) counted as variants — exclude from ratios; only their _share_ trending up is interesting. - **Experiments already concluded with a conclusion set** — the team decided; lingering _flag_ state is the only thing left worth checking. When in doubt, write a memory entry instead of emitting. ## MCP tools Direct calls (read-only): - `experiment-list` — cheap candidate discovery: id, name, status (draft / running / paused / stopped), dates, `feature_flag_key`. Filter by `status`; start here. - `experiment-results-get` — **the flagship detector**: exposure block (`total_exposures`, daily `timeseries`, native `sample_ratio_mismatch.p_value`, `bias_risk.multiple_variant_percentage`) plus per-metric `validation_failures` / `data: null`. Heavy response with many metrics — read the exposure + validation fields, skip the per-metric stats. New-engine experiments only; pass `refresh: false`. - `experiment-get` — full config for a candidate: `parameters.feature_flag_variants` (configured split), `parameters.rollout_percentage`, `recommended_sample_size`, `parameters.excluded_variants`, `exposure_criteria` (custom `exposure_event`, `multiple_variant_handling`, `filterTestAccounts`), `stats_config.method`, `holdout_id`, linked `feature_flag` (active, `version`, `bucketing_identifier`, `ensure_experience_continuity`, `filters.groups[].variant` overrides), `metrics` (each with `uuid` + fingerprint). Large response — candidates only. - `experiment-stats` — project-wide velocity aggregate (launched / completed last 30d, active count). Cheap context for the hygiene pass. - `experiment-timeseries-results` — day-by-day per-variant results for one metric (`metric_uuid` + `fingerprint` from the metrics array). Use sparingly, for the zombie "decide now" check. - `feature-flag-get-definition` / `feature-flags-activity-retrieve` — flag state and edit-history diffs; the latter is how you date mid-run mutations. - `activity-log-list` (`scope: "Experiment"`) — experiment-level edit timeline. - `execute-sql` against `events` — exposure analysis. Properties: `$feature_flag` (flag key) + `$feature_flag_response` (variant, incl. `$multiple`) on `$feature_flag_called`; `$feature/` on custom exposure events. - `read-data-schema` — confirm a custom exposure event and its properties exist before aggregating over them. - `inbox-reports-list` — pre-emit dedupe against the inbox. Harness-level: - `signals-scout-project-profile-get` / `signals-scout-scratchpad-search` / `signals-scout-runs-list` / `signals-scout-runs-retrieve` — orientation + dedupe. - `signals-scout-emit-signal` / `signals-scout-scratchpad-remember` — emit / remember. ## When to stop - No experiments in use → `not-in-use:` entry, close out empty. - All running experiments match their config (ratio in band, fresh exposures, no post-launch flag edits) → close out empty; refresh `pattern:` baselines if stale. - Candidates all gated by `noise:` / `addressed:` / `dedupe:` entries → close out. - You've emitted what's solid → close out. One sharp validity finding beats a laundry list of P3 hygiene nits. "Looked but found nothing meaningful" is a real outcome.