Engineering Blog · Post #77

Weekly Forecasts by Management: Baseline, Override, Audit

Friday 4pm: the CFO wants a premium forecast for next week. The manager doesn't want "whatever the pipeline math spits out" — they want to apply judgment, commit to a number, and have it tracked. InsightUW makes that a one-click snapshot.

The Problem

Forecasts are where spreadsheets win and workstations lose. Pipeline numbers drift through the week as UWs update win probabilities; by Friday no one remembers what Monday's forecast was. The VP overrides the baseline based on a broker call — but that override lives in an email, and next quarter there's no audit trail of what was committed vs. what landed.

The InsightUW Approach

InsightUW snapshots the forecast every Monday, at every scope (company / team / branch / UW), automatically. Management overrides stay untouched when the baseline recomputes. Every edit writes an audit row. Twelve weeks of history drives a sparkline.

graph TD subgraph Monday["Monday 08:00 UTC"] S1["Scheduler fires (async task or external cron)"] S2["For each scope × scope key × LOB: compute baseline = bound to date + Σ(proposed × win prob/100)"] S3["Upsert Weekly Forecast row (preserves override fields)"] end subgraph Manager["Manager authoring"] M1["Open Weekly Forecast UI"] M2["Row-level inline edit: override · committed · stretch confidence · notes"] M3["PUT /weekly/{guid}?actor=… role gate: manager / senior uw"] M4["History row written diff json + change reason"] end subgraph View["View"] V1["Table: baseline vs override vs committed vs stretch"] V2["Effective forecast = override (if set) else baseline"] V3["12-week sparkline per scope"] V4["Totals strip + % of target"] end S1 --> S2 --> S3 --> V1 M1 --> M2 --> M3 --> M4 --> V1 V1 --> V2 V1 --> V3 V1 --> V4

Scope Taxonomy

A single forecast row is keyed by (week_of, scope, scope_key[, lob]):
- scope=company, scope_key=ALL
- scope=team, scope_key=team name
- scope=branch, scope_key=branch code
- scope=uw, scope_key=underwriter name

The UI lets the manager flip between these and see the matching rows — a VP might spend her morning on team rows and her afternoon reviewing individual UW overrides.

The Baseline vs the Override

Baseline recomputes every Monday; the override, committed, stretch, confidence, and notes survive. Nothing gets clobbered.

Role Gate

PUT on a forecast row checks the caller's Team Member.team_role. Only manager and senior uw are allowed to edit. A regular UW opening the same page sees the data but the inputs are disabled — no accidental edits, no silent failures.

Audit Trail

Every change writes a Weekly Forecast History row with the old-value / new-value diff and the reason string. At quarter-end, the VP's question — "did we commit to $6.3M on week of March 2 or was that a late edit?" — gets answered in one query.

Under the Hood

Idempotent snapshot — the POST /weekly/snapshot endpoint is safe to re-run for the same week. Baseline fields get refreshed; override fields are preserved.
Self-healing scheduler — a FastAPI startup hook checks hourly whether today is Monday after 08:00 UTC and whether this week has been snapshotted; missed Mondays get picked up on the next hour.
External cron friendly — set WEEKLY_FORECAST_CRON_SECRET and a K8s CronJob / Airflow DAG can hit the endpoint from outside the pod.
12-week history — GET /weekly/history?scope=…&scope_key=…&weeks=12 drives the sparkline without extra DB cost.

What This Means for Management

Judgment stays in the system — overrides + notes + confidence live with the numbers, not in email.
No clobber — Monday recompute never overwrites a deliberate override.
Audit trail — every edit is diffed and attributed.
Sparklines — 12 weeks of snapshots visible next to the current week; no gut-feel "is this trending up?" questions.

What's Next

Next: Broker Book: Key Products Per Region with Target vs Actuals

Want forecasts the CFO will actually trust? Request a demo.