# AI Revenue Forecasting

_AI Features_

Monthly revenue forecast that combines pipeline commits with deal health + win probability + historical close rates. Shows "what your pipeline says" vs "what the AI thinks will actually close", with confidence bands and per-rep breakdowns.

## Steps
1. Pipeline > Forecast page now has an "AI Forecast" tab next to the standard Raw Pipeline view.
2. Top section: dual-bar chart showing Committed (your reps' raw pipeline value by month) vs AI Predicted (the model's estimate). Shaded confidence band = best/worst case.
3. Below: AI narrative summary, risks list (e.g., "Q3 pipeline depends on 3 deals worth >$200K each — concentrated risk"), opportunities list, and an honest accuracy note when data is thin.
4. By-rep table: each rep's open pipeline value, AI-predicted close, historical win rate, and gap (commitment minus prediction).
5. Every generation also writes a ForecastSnapshot row so we can backtest "predicted vs actual" once the month closes. Accuracy chart appears once you have ≥2 closed months of snapshots.

## Tips
- AI is intentionally conservative — it's tuned to under-predict rather than over-predict. If your reps commit $500K and the AI says $380K, the gap is the model saying "your reps are optimists, here's what historical close rates suggest".
- Seasonal patterns are extracted from the last 12 months of close data. Orgs with <3 months of history get a "low-confidence — interpret directionally" disclaimer in the summary.
- The reconciliation worker (closed-month actual fill-in) has a TODO and is deferred until July 2026 — there's nothing to reconcile until orgs have a month of forecast history. The accuracy panel shows "tracking — first reconciled month coming" until then.

## Example
A founder opens AI Forecast 2 weeks before quarter-end. Reps committed $480K. AI predicts $345K with low confidence; the risks list points at three deals where the deal-health card is amber. She does a same-day standup with the three deal owners; two are revived with action plans, one is dropped from the forecast. End-of-quarter actual: $362K — well above what those three deals would have delivered if left to drift.

## Troubleshooting
- **"Not enough deal history or pipeline to forecast yet" 404** — You need either (a) 3+ closed-won deals in the last 12 months, or (b) some open pipeline with expected close dates. Brand-new orgs have neither. Fix: Mark a few existing deals as won/lost with realistic close dates. Or wait until normal activity builds the history.
- **Forecast is way off vs. what reps committed** — By design — the AI is conservative. The gap is informative, not a bug. If reps consistently hit their commits, the model will catch up after a few quarters of training data. Fix: Don't delete the AI forecast. Use the gap as the conversation starter in your forecast review.
- **Accuracy chart never appears** — Needs ≥2 fully-closed months of ForecastSnapshot history. The reconciliation worker hasn't shipped yet (deferred TODO — revisit post-July 2026). Fix: Wait. The chart auto-appears once the data is there. No admin action required.

## Plans
Included in every plan. Forecast generation uses the standard tier on demand, cached 24h — at most one call per org per day. Toggleable per-org under Settings > AI Usage > AI Features (key: revenue_forecast).