category-trend-analyzer

カテゴリトレンド分析

目次

• 概要
• 入力契約
• ワークフロー
• 外れ値のルール
• 出力契約
• ガードレール

概要

取引をカテゴリ分けする目的は、毎月、何が変化したかを把握することです。このスキルは、すべてのカテゴリについて比較値（現在と移動平均、現在と予算、現在と前年同月）を計算し、外れ値を特定して、その要因となった取引を示します。重要度の下限を下回る小規模なカテゴリは除外し、ノイズを外れ値として扱いません。

入力契約

呼び出し元は、以下を指定します。

• transactions — カテゴリ分けされた、少なくとも13か月分の取引。
• budget — カテゴリごとの目標額を含む budget.json。
• period_start、period_end — 現在の対象期間（通常は暦月）。
• materiality_floor_cents — デフォルトは 5000（$50）。現在の支出がこの額を下回るカテゴリは集計しますが、外れ値としては検出しません。
• outlier_thresholds — デフォルトは { rolling_multiple: 1.5, budget_pct: 130 }。

ワークフロー

Trend Analysis Progress:
- [ ] Step 1: Roll up transactions by category for the current period
- [ ] Step 2: Roll up the prior 6 calendar months by category
- [ ] Step 3: Roll up the same-month-last-year by category
- [ ] Step 4: Compute deltas and percent changes
- [ ] Step 5: Apply outlier rules
- [ ] Step 6: Identify driver transactions for each outlier
- [ ] Step 7: Emit ranked list and totals

ステップ1 — 現在の対象期間の合計

各 category と category.subcategory について、[period_start, period_end] の期間における支出（負の amount_cents）を合計します。以下は除外します。

• income.*
• savings_investment.*
• financial.transfers_internal

これらは支出ではありません。キャッシュフローと貯蓄のビューで個別に追跡します。

ステップ2 — 過去6か月の平均

各カテゴリについて、過去6暦月それぞれの支出を合計し、その平均を算出します。「月次」の比較がユーザーの感覚と一致するよう、直近180日ではなく暦月を基準にします。

過去のデータが3か月未満の場合は、rolling_avg_confidence: low を設定し、予算のしきい値を超えた場合のみ外れ値を検出します（移動平均倍率の判定は省略します）。

ステップ3 — 前年同月比

1年前の同じ暦月の支出を合計します。該当データがない場合（データが1年未満の場合）、yoy_delta_cents: null を設定します。

ステップ4 — 差分の計算

指標	計算式
vs_rolling_pct	(current − rolling_avg) / rolling_avg × 100
vs_budget_pct	(current / budget) × 100（予算がある場合のみ）
vs_yoy_pct	(current − yoy) / yoy × 100

ステップ5 — 外れ値のルール

以下のいずれかに該当するカテゴリは外れ値です。

• vs_rolling_pct ≥ (rolling_multiple − 1) × 100（デフォルトでは、6か月平均を50%以上上回る）かつ current_cents ≥ materiality_floor_cents。
• vs_budget_pct ≥ budget_pct（デフォルトでは予算の130%以上）かつ予算が存在する。
• current_cents ≥ 2 × rolling_avg_cents かつ current_cents ≥ materiality_floor_cents → 重要度は high（spending-analyst の仕様に基づくリアルタイムアラート）。

各外れ値には、以下が含まれます。

• severity — high（移動平均の2倍以上）、medium（移動平均の1.5倍以上、または予算の130%以上）、low（重要度の下限を上回るものの、しきい値内 — 文脈を示すためだけに表示）。
• reason — 該当したルール。

ステップ6 — 要因となった取引

各外れ値について、金額の絶対値が大きい順に上位3～5件の取引を特定します。これらは、ブリーフィングで「外れ値の要因」を説明するための明細です。

1件の取引が外れ値の60%を超える割合を占める場合は、single_driver: true を設定します。これにより、アナリストは説明を適切に表現できます（「IKEA で850ドル使いました。1回の買い物で、住宅メンテナンスの平均は120ドルでした」など）。

ステップ7 — 順位付け

dollar_impact_cents = |current_cents − rolling_avg_cents| で外れ値を順位付けします。金額の変動が大きいものを先にし、割合が小さくても金額が大きい変動を、割合が大きくても金額が小さい変動より重視します。

外れ値のルール

具体例：

現在	直近6か月の平均	予算	結果
食料品 $1,200	$850	$900	中 — 直近の平均の1.41倍、予算の133％
旅行 $3,400	$300	$400	高 — 直近の平均の11.3倍ですが、重要性の基準を満たしています
趣味 $42	$20	$30	フラグなし（重要性の基準である$50未満）
住宅メンテナンス $850	$120	$150	高 — 直近の平均の7.1倍、IKEAでの単一要因による出費
外食 $1,800	$1,200	—	中 — 直近の平均の1.5倍、予算は未設定
光熱費（8月） $3,200	$2,100	$2,400	中 — 熱波、直近の平均の1.5倍、予算の133％。前年同期比は+5％のため、生活習慣の変化ではなく季節要因

出力仕様

{
  "period": { "start": "2026-04-01", "end": "2026-04-30" },
  "totals": {
    "spend_cents": 624800,
    "spend_cents_vs_rolling": 78400,
    "spend_cents_vs_budget": -25200,
    "categories_above_floor": 18,
    "outliers_count": 3
  },
  "categories": [
    {
      "category": "food",
      "subcategory": "groceries",
      "current_cents": 102000,
      "rolling_avg_cents": 85000,
      "yoy_cents": 92000,
      "budget_cents": 90000,
      "vs_rolling_pct": 20.0,
      "vs_budget_pct": 113.3,
      "vs_yoy_pct": 10.9,
      "severity": "low",
      "outlier": false
    },
    {
      "category": "travel",
      "subcategory": null,
      "current_cents": 340000,
      "rolling_avg_cents": 30000,
      "yoy_cents": 18000,
      "budget_cents": 40000,
      "vs_rolling_pct": 1033.3,
      "vs_budget_pct": 850.0,
      "vs_yoy_pct": 1788.9,
      "severity": "high",
      "outlier": true,
      "reasons": ["above_rolling_multiple_2x", "above_budget_threshold"],
      "drivers": [
        { "tx_id": "tx_20260408_002", "amount_cents": -312000,
          "merchant": "Delta Air Lines", "single_driver": true,
          "share_of_outlier_pct": 91.8 }
      ]
    }
  ],
  "rankings": {
    "biggest_growers": ["travel", "home_maintenance", "restaurants"],
    "biggest_shrinkers": ["entertainment", "transportation.gas"]
  }
}

ガードレール

• まず重要性を確認します。 趣味の$20の超過にはフラグを付けません。ユーザーの注意は最も貴重なリソースです。
• サブカテゴリと親カテゴリを二重計上しないでください。 どちらか一方の階層を選びます。概要には最上位カテゴリを、詳細分析にはサブカテゴリを使います。どちらを表示するかは、spending-analyst エージェントが決定します。
• 年間で変動の大きいカテゴリ（auto_insurance、property_tax、home_insurance）では、請求月に日常的に10倍以上の外れ値が発生します。recurring.jsonに記録された加盟店の年間周期と急増が一致する場合は、フラグを付けないでください。spending-analyst エージェントのseasonal-calendarサブシグナルを使用します。
• マイナスの外れ値が必ずしも悪いとは限りません。 カテゴリの支出がゼロになった場合、請求漏れ（光熱費の自動引き落としが停止しているなど）の可能性があります。どちらの方向にもフラグを付けますが、説明は変えてください。
• このスキルでは原因を分類しないでください（「昇給した」「子どもがキャンプに通い始めた」など）。データを提示し、説明は分析エージェントに任せます。