## TL;DR
A shifted column mean signals distribution drift: compare the full distribution, not just the mean, against the reference window using percentiles and a histogram, and segment by the dimensions that feed the column to find which segment moved. A mean shift from one segment is a data event; a shift everywhere at once is usually a definition or unit change.

```text
distribution drift error failed: column mean shifted beyond threshold failure
```

## Use this when
- The check or run fails with this symptom: the distribution check fails with the column mean beyond the allowed shift.
- You are working on a column whose mean moved beyond the drift threshold and the failure repeats on the same data or configuration.
- You need the failing rows, rule, or stage isolated before changing thresholds or code.

## Not for this skill when
- A mean shift fully explained by one extreme outlier batch, which needs row-level cleanup rather than drift handling instead.
- The error text names a different tool, stage, or root cause. Match the verbatim error first and use that skill.

## Steps
1. Compute percentiles and a coarse histogram for the current window and the reference window. Verify: both distributions are described beyond the mean
2. Segment the column by its main dimensions and find which segments moved and which stayed stable. Verify: the moving segments are identified
3. Inspect the moving segment for definition, unit, or source changes coinciding with the shift. Verify: a coincident change is found or ruled out
4. If the shift is a genuine new behaviour, update the reference window deliberately and note the change on the monitor; if it is a defect, fix and reload the segment. Verify: the monitor reference and the data agree with the decision
5. Confirm the drift check passes on the next window without further unexplained movement. Verify: the next window is stable under the check

## Variant phrasings
### distribution drift column mean shifted threshold
The verbatim drift phrasing.
### column distribution changed segment drift
The segmentation phrasing for finding the moving segment.
### data drift alert definition change unit change
The definition-change phrasing for global shifts.

Compatibility: Distribution monitors, Soda distribution checks, and Great Expectations quantile expectations

## Why it happens
Means move when populations mix differently, units change, or one segment's behaviour changes, and a threshold on the mean alone cannot separate those. The drift alert is the start of a segmentation exercise, not a verdict on data quality.

## Edge cases / pitfalls
- Store the reference distribution with the monitor so the comparison is reproducible months later.
- Pair mean drift with a missing-rate drift check. Population changes often move both.

## Provenance

Resolved from the public thread: https://vectle.com/posts/pst_WHlsBUe4-saQecY87j3ceQ