configuring-experiment-rollout

Files (2)

• SKILL.md
• changing-distribution-after-launch.md · references/

SKILL.md (first lines)

# Configuring experiment rollout

This skill answers: **Who sees what variant?**

## Recommended approach: equal split + adjust rollout percentage

In most cases, experiments work best with an equal split. If you want to limit exposure to the test variant, adjust the rollout percentage instead.

Why equal splits are better:

- Equal splits maximize statistical power — each variant has the same sample size
- Equal splits balance traffic and thus reach significance faster
- Increasing user exposure throughout the experiment through increasing rollout is clean (changing split mid-experiment can cause users to switch variants, which is bad for user experience and data quality)

Always default to an equal split unless the user explicitly requests otherwise.

## When an uneven split is required

Uneven splits combined with the default "Exclude from analysis" handling can introduce bias.
If the experiment observes multi-variant users (users exposed to more than one variant) then those are
dropped asymmetrically — the smaller variant loses a larger fraction of its assignments. If those users
behave differently from the rest, the smaller variant's metrics will be skewed.

The right mitigation depends on experiment state:

1. **Pre-launch, or live but with few exposures so far — use an equal split and reduce the overall
   rollout.** Achieves the same test-variant exposure without the bias and preserves statistical
   power. See the disambiguation question below.
2. **Live experiment with significant exposures — switch multivariate handling to "First seen
   variant".** Changing the split mid-run reassigns users across variants (anti-pattern; see
   "Changing rollout on a running experiment" below). Switching handling instead keeps everyone in
   their original variant and avoids the asymmetric exclusion. See `configuring-experiment-analytics`
   for how to set this. Note that "first seen" handling can introduce other biases, but it's
   preferable to mid-run reassignment.

## The two rollout controls

There are two separate controls that determine who sees what.
Both live on the linked feature flag, sent through the `feature_flag` object in the flag's own shape (not the deprecated `parameters` keys).

### 1. Variant split (`feature_flag.filters.multivariate.variants`)

How users **inside** the experiment are distributed across variants.

- Array of `{key, name, rollout_percentage}`, where the `rollout_percentage` values must sum to 100
- Minimum 2 variants, maximum 20
- No specific variant key is required — the analysis baseline defaults to the variant keyed `"control"` when present, else the first variant
- Default: control 50% / test 50%

If the user says "A/B/C test" without naming keys, key the baseline `"control"` (the convention) and create additional variants for the others; if they ask for specific keys, use them as-is with the baseline first.

### 2. Overall rollout (`feature_flag.filters.groups[0].rollout_percentage`)

What percentage of **all** users enter the experiment at all, sent as a single rollout group: `groups: [{ "properties": [], "rollout_percentage": N }]`.
Default: 100%.

Users not included are excluded entirely: they don't see any variant and are **not part of the analysis**.

### Where these are sent

Both controls live inside `feature_flag.filters`:

```json
{
  "feature_flag": {
    "filters": {
      "multivariate": {
        "variants": [
          { "key": "control", "name": "Control", "rollout_percentage": 50 },
          { "key": "test", "name": "Test", "rollout_percentage": 50 }
        ]
      },
      "groups": [{ "properties": [], "rollout_percentage": 100 }]
    }
  }
}
```

`filters` may also carry `aggregation_group_type_index` (to run the experiment on a group type rather than individual users) and `payloads` (JSON-encoded strings keyed by variant key).
On a **running** experiment, any flag-config change must also send `update_feature_flag_params: true`, otherwise the API rejects the update before it reaches the flag (see "Changing rollout on a running experiment").

### How they interact

These two controls multiply:

| Overall rollout | Variant split      | % seeing test | % in analysis |
| --------------- | ------------------ | ------------- | ------------- |
| 100%            | 50/50              | 50%           | 100%          |
| 100%            | 75/25 control/test | 25%           | 100%          |
| 50%             | 50/50              | 25%           | 50%           |
| 25%             | 50/50              | 12.5%         | 25%           |

## The disambiguation question

**CRITICAL**: If the user requests an uneven variant split (e.g. "60/40", "70/20/10") or mentions a
specific percentage that could refer to either the split or the rollout (e.g. "roll out to 25%"), you
MUST clarify before proceeding. This covers two cases:

### Case 1: Single percentage ("25%", "roll out to 40%")

The percentage is ambiguous — it could mean a variant split or a rollout change. Ask:

> There are two ways to get 25% of users seeing the test variant:
>
> 1. **Reduced rollout with equal split** (recommended): reduce the overall rollout and split
>    variants equally. Only a subset of users enter the experiment, and of those, each variant
>    gets the same share.
>    Equal splits maximize statistical power and avoid bias.
> 2. **Asymmetric split**: keep 100% rollout but give the test variant only 25%.
>    All users enter the experiment, but the uneven split reduces power on the smaller variant
>    and risks bias.
>
> Which approach do you prefer?

Adjust the numbers to match whatever percentage the user requested.

### Case 2: Uneven ratio ("60/40", "70/30", "80/20", etc.)

The ratio looks like an explicit variant split, but a reduced rollout with an equal split is almost

From PostHog/skills, MIT.