cost-anomaly

セッション単位の外れ値検出 — cost-burn の集計トレンドシグナルに対応する診断機能です。

質問	スキル
「集計レートは加速していますか？」	cost-burn
「異常な外れ値となっている特定のセッションはどれですか？」	cost-anomaly ← これ
「集計で支出を抑えられたでしょうか？」	cost-counterfactual
「予算に到達するのはいつですか？」	cost-projection

アルゴリズム

実装: scripts/anomaly.mjs。

1. cost-tracking 名前空間からすべての session-* レコードを読み取ります。
2. --since の期間で絞り込みます（デフォルト: 全期間）。
3. median(total_cost_usd) と MAD = median(|x - median|) を計算します。
4. セッションごとの修正 z スコア（Iglewicz-Hoaglin 1993）: z = 0.6745 * (x - median) / MAD
5. |z| > --threshold（デフォルト 3.5）のセッションにフラグを付けます。

なぜ平均値 + 標準偏差ではなく MAD なのか？

手法	問題点
mean + sigma	1 回の $50 のセッションで平均値と標準偏差の両方が大きく膨らみ、その後の外れ値が新しい「正常」範囲に隠れてしまいます。少数のサンプルでは致命的です。
median + MAD	どちらの推定量もデータの最大 50% を無視するため、外れ値そのものによって値が変動することはありません。n=10 でも頑健です。標準的なカットオフ値 |z| > 3.5 は Iglewicz-Hoaglin（1993）に基づいています。

スモークテストの記録（$0.08〜$0.12 のベースラインセッション 5 件 + 外れ値 1 件 $5.00）

| Sessions considered | 5 |
| Threshold (|modified z|) | 3.5 |
| Median spend | $0.100000 |
| MAD | $0.010000 |
| Min / Max | $0.080000 / $5.000000 |
| **Outliers found** | **1** |

## Outlier sessions
| Session | Spend | Deviation | Modified z | Direction |
| outlier- | $5.000000 | +$4.900000 | 330.505 | high |

終了コード

$ cost anomaly --alert-on-outliers 1
⚠ ALERT: found 1 outlier session(s) (|modified z| > 3.5); threshold was ≥1
exit 1

$ cost anomaly --alert-on-outliers 5
✓ found 1 outlier session(s); under threshold ≥5 — OK
exit 0

CI との統合

# Fail the build if any session this week is a >3.5σ outlier
cost anomaly --since 7d --alert-on-outliers 1 || investigate-bad-session

cost-burn と組み合わせると最も有用です。

cost burn  --alert-on-acceleration-pct 50  || page-oncall   # rate-of-change alert
cost anomaly --alert-on-outliers 1         || investigate   # point-anomaly alert

これらを組み合わせることで、「平均は変化しているか？」と「単独の異常な セッションはあるか？」の両方をカバーできます。どちらも独立して発生する可能性があります。

エッジケース

• n < 3: 「データ不足」というメッセージを出力し、終了コード 0 を返します。1〜2 個のサンプルに対する MAD は意味をなしません。
• MAD = 0: セッションの 50% 以上がまったく同じ支出額であるため、z スコアがゼロに収束します。ゼロ除算の代わりに説明を出力します。よくある原因は、ドライランのセッションがすべて $0 であることです。
• 低方向の外れ値: 通常、過剰支出ではなく、クラッシュまたは中断されたセッションです。出力テーブルには方向が明示されるため、運用担当者が正しく解釈できます。
• MAD が非常に小さい場合: ごく小さな絶対偏差でも巨大な z スコアになります。MAD=$0.01 のときの $5 の外れ値は z=330 となりますが、これは正しく、バグではありません。

方向列

方向	考えられる原因	対応
high	長時間のセッション、高コストのティアにとどまっている、またはループが止まらない	調査するには cost report + cost conversation を実行します
low	クラッシュ、中断されたセッション、または未完了の作業	セッションが正常に完了したことを確認します