AgentSkillsCN

Forecast

预测

SKILL.md

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