forecast

name	forecast
description	Generate time-series forecasts for key metrics using statistical methods. Supports naive baselines, seasonality detection, and exponential smoothing. Triggered when users ask "what will revenue look like next month?", "forecast DAU", or invoke `/forecast`.

Skill: Forecast

Purpose

Generate time-series forecasts for key metrics using the forecast_helpers library. Supports naive baselines, seasonality detection, and exponential smoothing — enough to answer "what should we expect next?" without complex modeling.

When to Use

• User asks "what will revenue look like next month?" or "forecast DAU"
• After trend analysis reveals a pattern worth projecting
• When sizing an opportunity that depends on future values
• Invoked as /forecast

Invocation

/forecast {metric} — forecast the named metric /forecast {metric} periods=30 — specify forecast horizon /forecast {metric} method=holt_winters — specify method

Instructions

Step 1: Prepare the Data

1. Identify the metric and its source table from the metric dictionary (<workspace>/knowledge/datasets/{active}/metrics/) or from user specification.
2. Query the data aggregated to the appropriate granularity (daily/weekly/monthly).
3. Create a pandas Series with DatetimeIndex.
4. Clean: forward-fill NaN, drop leading nulls.
5. Require at least 14 data points. If fewer: "Not enough history for forecasting."

Step 2: Detect Seasonality

Run detect_seasonality() from helpers/forecast_helpers.py:

• If seasonality detected, report: "Found {strength} {period}-day seasonality."
• Store the dominant period for use in Step 3.

Step 3: Generate Forecasts

Run multiple methods and compare:

1. Naive (last value): naive_forecast(series, periods, method='last')
2. Naive (seasonal): If seasonality detected: naive_forecast(series, periods, method='seasonal_naive')
3. Exponential smoothing (auto): exponential_smoothing(series)
4. Holt-Winters: If seasonality detected and enough data: exponential_smoothing(series, seasonal_period=dominant_period)

Compare MSE across methods. Select the best-fit method.

Step 4: Generate Chart

Using chart_helpers:

1. Call swd_style()
2. Plot historical data as a solid line
3. Plot forecast as a dashed line with lighter alpha
4. Add confidence band (±1 std of residuals) as shaded area
5. Mark the historical/forecast boundary with a vertical dashed line
6. Use action_title() with a forward-looking title
7. Save to working/forecast_{metric}_{DATE}.png using save_chart()

Step 5: Present Results

Report:

• Best method and why (lowest MSE)
• Forecast values for key periods (next 7/14/30 days)
• Seasonality summary
• Confidence level (based on residual magnitude)
• Caveats: "Forecasts assume past patterns continue. External factors not modeled."

Rules

1. Always run at least 2 methods for comparison
2. Never present a forecast without stating assumptions
3. Always include a naive baseline so the user can see if the model adds value
4. Flag if residuals show systematic patterns (model may be misspecified)
5. If the data has a structural break, warn that forecasts may be unreliable

Edge Cases

• Constant series: Report "No variation — forecast is the constant value"
• Strong trend + no seasonality: Use Holt's (double) exponential smoothing
• Very short history (<30 points): Only use naive methods, warn about accuracy
• Data gaps: Interpolate or warn, depending on gap size