cash-flow-forecaster

キャッシュフロー予測

目次

• 概要
• 入力仕様
• ワークフロー
• 裁量支出のモデル化
• 出力仕様
• ガードレール

概要

月平均だけでは、給料が振り込まれるのが5日なのに、家賃の引き落としが3日に行われるかどうかは分かりません。このスキルでは、次の情報を組み合わせ、予測期間における各現金口座の日次の期末残高を予測します。

• 今日の実際の残高。
• 予測期間内に next_expected_date がある、予定済みの定期的な入出金すべて。
• 過去6か月の非定期支出から算出した、推定裁量支出分。

残高が設定可能な安全下限を下回ると予測される日と、口座ごとの残高の底を明らかにします。

入力仕様

呼び出し元は次の情報を渡します。

• accounts — 現金口座の配列：{id, type, current_balance_cents, safety_floor_cents}。
• recurring — status: active でフィルタリングした recurring.json。
• transactions — 各現金口座の過去180日分のカテゴリ分類済み取引。
• today — ISO形式の日付。
• horizon_days — デフォルトは60です。
• category_overrides（任意）— ユーザーが把握している明示的な一時支出（例：予定されている旅行の予約金）。

ワークフロー

Forecast Progress:
- [ ] Step 1: Initialize daily ledger per account with current balance
- [ ] Step 2: Project recurring flows in the horizon window
- [ ] Step 3: Compute discretionary tail (rolling 6-month average)
- [ ] Step 4: Spread discretionary across days
- [ ] Step 5: Apply category_overrides
- [ ] Step 6: Compute daily ending balance
- [ ] Step 7: Flag below-floor days; identify trough
- [ ] Step 8: Compute confidence interval around projection

ステップ1 — 初期化

各口座について、[today, today + horizon_days] の各日に対して ledger[account_id][day] = 0 を作成します。ledger[account_id][today].opening = current_balance_cents を設定します。

ステップ2 — 定期的な入出金を予測

有効な定期エントリごとに、next_expected_date から cadence を加算しながら予測期間を過ぎるまで進めます。各発生日について、amount_cents_typical を ledger[recurring.account_id][occurrence_date].flows に追加します。

給与について、週末と祝日を処理します。ほとんどの給与振込は平日に行われます。next_expected_date が週末の場合、入金は次の平日に繰り延べます。出金は暦日どおりに処理します。

ステップ3 — 裁量支出分を算出

各口座について、次の値を算出します。

discretionary_total_180d = Σ amount_cents over last 180 days
                            where category NOT IN
                            { financial.transfers_internal, savings_investment.*,
                              income.* }
                            and tx_id not in any recurring cluster

discretionary_daily_avg = discretionary_total_180d / 180（これは裁量支出を表すため、負の値です）。

ステップ4 — 裁量支出を分散

最もシンプルな方法は、その口座の予測期間中の各日から discretionary_daily_avg を差し引くことです。

曜日ごとの傾向が重要な場合は、曜日別の平均（たとえば月曜日と金曜日の違い）を算出し、曜日に応じて適用する方法がより適切です。transactions に少なくとも90日分のデータがあり、曜日ごとの分散に実質的な差がある場合を除き、シンプルな方法をデフォルトとします。

ステップ5 — 上書きを適用

category_overrides の各エントリについて、明示的な {date, account_id, amount_cents, reason} を該当日のフローに追加します。

ステップ6 — 残高を順次計算

balance[t] = balance[t-1] + Σ flows on day t

口座ごとに実行残高を追跡します。

ステップ7 — 安全下限を下回る日を特定

各口座について、balance[t] < safety_floor_cents となる日を特定します。次の値を識別します。

• trough_balance_cents — 予測期間中の最低残高。
• trough_date — 最低残高になる日。
• first_breach_date — 初めて安全下限を下回る日。
• breach_days — 安全下限を下回る日数。

ステップ8 — 信頼区間

裁量支出の分散にはばらつきがあります。裁量支出の30日間のローリング標準偏差を算出し、予測を balance ± 1.5σ × √days_from_today の幅で示します。ユーザーが過度に正確な単一の推定値ではなく範囲を確認できるよう、残高の底となる日に lower_balance_cents と upper_balance_cents を提示します。

任意支出のモデル化

デフォルト：過去180日間の単純な日平均。定期支出にも、振替・投資・収入にも該当しないすべての支出が対象です。

改善策（データで裏付けられる場合にのみ適用してください）：

• 曜日。 土曜日と日曜日は支出が多くなる傾向があります。曜日ごとの係数を適用してください。
• 月初と月末。 任意支出は給料日の前後に急増する傾向があります。定期的な入金が1日と15日にある場合は、給料日後に小幅な増加を見込むことを検討してください。
• 季節性。 11～12月の休暇シーズンの支出増加は実際にあります。予測期間がこれらの月にまたがる場合は、+20%の倍率を適用し、その旨を記録してください。

適用した改善策はすべて、出力のmethodologyフィールドに記録し、ユーザーが前提を正確に確認できるようにしてください。

出力仕様

{
  "horizon": { "start": "2026-04-25", "end": "2026-06-24", "days": 60 },
  "accounts": [
    {
      "account_id": "acc_chk_001",
      "starting_balance_cents": 1247500,
      "ending_balance_cents": 932100,
      "trough_balance_cents": 124300,
      "trough_date": "2026-05-30",
      "trough_band_cents": [82100, 166500],
      "first_breach_date": null,
      "breach_days": 0,
      "safety_floor_cents": 100000
    }
  ],
  "daily": [
    { "date": "2026-04-25", "balances": { "acc_chk_001": 1247500 }, "flows": [] },
    { "date": "2026-05-01", "balances": { "acc_chk_001": 1093200 },
      "flows": [
        { "account_id": "acc_chk_001", "amount_cents": -273500, "label": "Mortgage P&I", "type": "recurring" },
        { "account_id": "acc_chk_001", "amount_cents": -78000,  "label": "Mortgage escrow", "type": "recurring" }
      ]
    }
  ],
  "alerts": [],
  "methodology": "Daily discretionary derived from 180-day rolling average across 23 non-recurring categories; 1.5σ confidence band; weekend-adjusted paychecks; no seasonal multiplier in this horizon."
}

違反が検出された場合：

{
  "alerts": [
    {
      "severity": "high",
      "type": "projected_below_floor",
      "account_id": "acc_chk_001",
      "first_breach_date": "2026-05-15",
      "trough_balance_cents": -42000,
      "trough_date": "2026-05-30",
      "drivers": [
        { "date": "2026-05-15", "amount_cents": -350000, "label": "Property tax (annual)" }
      ],
      "suggested_actions": [
        "Move $50,000 from savings before 2026-05-14",
        "Defer discretionary spend by $20,000 across the next 3 weeks"
      ]
    }
  ]
}

ガードレール

• 現金以外の口座については、決して予測しないでください。 証券口座、401k、HSAの残高はキャッシュフローではなく、保有資産です。対象から除外してください。
• 住宅ローンの繰り上げ返済は明示的に扱い、暗黙に含めないでください。 ユーザーの通常の住宅ローン返済は定期支出ですが、元本の追加返済はcategory_overrideです。元本の追加返済は予測しないでください。
• 任意支出の平均は予測ではなく、余裕分です。 この幅は、ユーザーにあくまで推定値だと思い出してもらうためのものです。計画に用いる数値は中央値ではなく、下限値です。
• 二重計上しないでください。 定期支出は定義上、任意支出の計算から除外されます（定期支出のクラスタに関連付けられた取引は、任意支出の対象には含まれません）。
• 頻繁に更新してください。 60日間の予測も、新しい取引が入ると数日で古くなります。エージェント層では、新たなデータが取り込まれるたびに再実行してください。