metric-anomaly

Command: metric-anomaly

Detect point-in-time anomalies in a single metric — recent spikes, drops, and clusters. Produces a verdict on whether something unusual happened at a specific moment. Does not test for trend-level drift (run metric-drift for that).

---

Prerequisites

Before this command runs, Steps 0, 1, and 1.5 from references/execution.md must have completed — input validation, normalized metric series object, and project profile resolution. If any of those haven't happened, do them first.

If the user's input is a saved report but the metric is a funnel or retention report, see the "Special cases" section at the bottom.

Prerequisite — classify metric_type

Classify the metric per the metric_type table in SKILL.md and store metric_type on the series object before firing any queries.

---

Phase 1 — Fetch series (2 queries, parallel)

Fire both queries simultaneously:

Query	Window	Granularity	Purpose
Q1-hourly	Last 7 days	hour	Recent-blip detection
Q1-daily	Last 30 days	day	Recent-day detection against a fuller baseline

Use the query_template from the metric object; override only dateRange and unit (granularity). Do not re-apply filters — they're already baked in.

Build the query body from query_template with only dateRange and unit (granularity) overridden. Use timeComparison when a single call can cover both windows.

---

Phase 2 — Outlier test (additive seasonal baseline + robust residual)

For each series independently, fit an additive seasonal baseline, then test each point's residual against the spread of all residuals. One test per series — the residual test below does the work the old Z-score/IQR split did, without the per-cell sample-size problem.

Why additive, not per-cell

A 7-day hourly series has exactly 168 points. Bucketing into 168 independent hour-of-day × day-of-week cells leaves one observation per cell — no μ, no σ, no IQR to compute. Modelling hour-of-day and day-of-week as additive effects instead pools across the margins: ~30 parameters estimated from 168 points (~5–6 obs each), so the baseline is actually estimable. A robust fit also self-protects — it keeps the spike being hunted from inflating its own baseline and masking itself.