ai-analyst-lab/.claude/skills/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 (.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