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 (

   .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