demand-forecast-explainer

Overview

Demand planners at retailers and grocers routinely interpret complex ML forecast outputs and manually explain variance to leadership. This skill automates that translation: given forecast data (uploaded file, pasted output, or verbal description), it produces a plain-English narrative explaining what changed, why, what the confidence bands mean for inventory decisions, and what action to take.

Workflow

<Definition - Confidence Interval> A range around the point forecast representing the model's uncertainty. For executive audiences, translate as: "We're [X]% confident demand will land between [low] and [high] units. Plan inventory to the [percentile] if you want to maintain [service level]% fill rate." </Definition - Confidence Interval>

<Definition - Forecast Drivers> Factors the ML model identified as contributing to the forecast change. Common categories: Seasonality, Promotions/Events, Price Changes, External Signals (weather, economic indicators), Trend Shifts, New Product Introductions, Supply Disruptions, Competitive Actions. See references/driver-taxonomy.md for the full taxonomy and plain-English descriptions. </Definition - Forecast Drivers>

<Definition - Variance> The difference between the current forecast and a prior baseline (previous forecast cycle, same period last year, or budget plan). Always state variance in both absolute units and percentage terms. </Definition - Variance>

<Definition - Inventory Decision Language> Translating statistical outputs into actionable supply chain terms:

• Confidence band width → "How much safety stock do we need?"
• Point forecast shift up → "Do we need to pull forward purchase orders?"
• Point forecast shift down → "Should we slow inbound or divert inventory?"
• High uncertainty → "Consider delaying commitment until next forecast cycle" </Definition - Inventory Decision Language>

<Workflow - Explain Forecast description="Core workflow: ingest forecast data and produce a plain-English explanation" tools=[file_read, file_read_pdf, file_read_docx] triggers=["Why did the forecast change?", "Explain this forecast", "What drove the variance?", "Forecast for [SKU/category]"]

1. [Ask user] Collect the forecast data. Accept any of:

   • A file upload (CSV, Excel, PDF report, Word doc)
   • Pasted data (table, numbers, or model output)
   • A verbal description ("forecast went from 10K to 14K units for Q3")

   If the user hasn't provided a prior baseline (previous forecast or actuals), ask: "What was the previous forecast or actual demand for comparison?"

   Validate: At minimum, have a current forecast value AND a comparison point (prior forecast, budget, or actuals). If fails: Re-prompt the user for the missing piece (current forecast or comparison baseline).

2. [Agent] Parse and structure the data.

   • If file: read with appropriate tool (file_read for CSV, file_read_pdf for PDF, file_read_docx for Word)
   • Identify: SKU/category, time periods, point forecast values, confidence intervals (if present), prior baseline values
   • Calculate: absolute variance, percentage variance, direction of change
   • Note: which columns/fields represent upper/lower bounds, which represent point estimates

   Validate: At least one point forecast value and one comparison point successfully extracted. If fails: Ask user to clarify which columns contain forecast values vs. actuals, or request the data in a different format.

3. [Agent] Identify and rank the drivers.

   • Look for driver attribution in the data (feature importance, decomposition columns, commentary)
   • If drivers are explicitly labeled in the data, rank by magnitude of contribution
   • If drivers are NOT in the data, infer from available signals:
     • Time of year → seasonality
     • Promotional flags → promotion lift
     • Price columns → price elasticity effect
     • External columns (weather, CPI, etc.) → external signals
   • If insufficient data to determine drivers, state this clearly and ask the user what they believe changed
   • Reference: references/driver-taxonomy.md for standard driver categories and descriptions

   Validate: At least one driver identified (either confirmed from data or inferred with explicit caveat). If fails: Present the variance calculation from step 2 without driver attribution, and ask the user what business context might explain the change.

4. [Agent] Translate confidence intervals.

   • Convert statistical bounds into inventory language:
     • Width of band → uncertainty level → safety stock implication
     • Upper bound → maximum plausible demand → risk of stockout if planned to point forecast
     • Lower bound → minimum plausible demand → risk of overstock if planned to upper bound
   • Express in units the audience cares about: units, cases, pallets, days of cover, or dollars
   • If confidence level is stated (e.g., 80%, 95%), explain what it means practically

   Validate: Confidence interval translated into at least one practical inventory metric (days of cover, safety stock units, or service level percentage). If fails: If no confidence interval was provided in the source data, skip this section and note "Confidence interval not available" in the output.

5. [Decide] Select output format based on audience level:

   • VP/SVP → Use <Template - Executive Explainer>
   • Director → Use <Template - Executive Explainer> + add a "Supporting Detail" section with driver decomposition table
   • Demand Planner → Use <Template - Technical Explainer>

   Validate: Exactly one template selected based on audience_level input or default. If fails: Default to VP/SVP (executive summary) if audience level is ambiguous.

6. [Agent] Generate the explanation using the selected template.

   • Fill in all template fields with the structured data from steps 2-4
   • Ensure every claim references the source data
   • Round numbers per audience rules
   • End with a specific, actionable recommendation

   Validate: Output contains all required template sections (Bottom Line, What Changed, Why It Changed, Recommended Action) with no placeholder text remaining. If fails: Identify which template fields could not be populated due to missing data, fill them with "[Data not provided]", and note the gaps at the end of the output.

</Workflow - Explain Forecast>

<Workflow - Interpret Confidence Band description="Focused sub-workflow when user specifically asks about confidence intervals" tools=[file_read] triggers=["What does the confidence interval mean?", "confidence band", "how certain is this forecast?"]

1. [Ask user] What confidence interval or band are you looking at? Collect:

   • The point forecast value
   • The upper and lower bounds
   • The confidence level (e.g., 80%, 95%) if known
   • The product/category and time period

   Validate: At minimum, have a point forecast and at least one bound (upper or lower). If fails: Ask user to provide the specific numbers from their forecast output.

2. [Agent] Translate into inventory decision language:

   • Band width as a % of point forecast → characterize uncertainty (tight <10%, moderate 10-25%, wide >25%)
   • Service level mapping: "To achieve 95% fill rate, plan to [upper bound percentile]"
   • Safety stock implication: additional units needed above point forecast
   • Inventory cost of uncertainty: rough dollar value of carrying extra safety stock

   Validate: Uncertainty characterized as tight/moderate/wide with corresponding percentage calculation. If fails: If only one bound is available, characterize uncertainty directionally (e.g., "upside risk of X units") rather than as a full band width.

3. [Agent] Produce output using the Confidence Band section of <Template - Executive Explainer>. Include a specific recommendation: plan to point forecast (low risk) vs. plan to upper bound (high service level) vs. split the difference.

   Validate: Output includes a specific numeric recommendation (plan to X units) with service level rationale. If fails: Provide a qualitative recommendation (e.g., "plan conservatively above point forecast") and explain what additional data would enable a precise recommendation.

</Workflow - Interpret Confidence Band>

<Workflow - Compare Forecast Cycles description="When user wants to understand why THIS cycle's forecast differs from LAST cycle" tools=[file_read, file_read_pdf] triggers=["Why is this different from last month's forecast?", "forecast revision", "what changed since last cycle?"]

1. [Ask user] Collect both forecast cycles:

   • Current forecast (file or values)
   • Previous forecast (file or values)
   • Confirm they cover the same forward-looking periods

   Validate: Two distinct forecast values or files obtained, covering overlapping time periods. If fails: Ask user which specific periods to compare, and whether they have the prior cycle's forecast available.

2. [Agent] Calculate cycle-over-cycle variance:

   • Period-by-period delta (absolute and %)
   • Net revision direction (up/down/mixed)
   • Identify periods with largest revisions

   Validate: At least one period-over-period comparison calculated with both absolute and percentage variance. If fails: If periods don't align between cycles, ask user to confirm which periods should be compared or whether to use aggregate totals.

3. [Agent] Attribute the revision to drivers:

   • New data incorporated since last cycle (actuals, promotions locked in, etc.)
   • Model retraining or parameter updates
   • External signal changes (weather forecast updates, economic data releases)
   • Manual overrides applied or removed

   Validate: Revision attributed to at least one category (new information vs. model recalibration), with explicit statement of which is confirmed vs. inferred. If fails: Present the variance without attribution and ask the user: "Do you know whether any new promotions were locked in, the model was retrained, or manual overrides were changed since last cycle?"

4. [Agent] Produce explanation using <Template - Executive Explainer> with emphasis on "What's New Since Last Cycle" framing.

   Validate: Output clearly distinguishes cycle-over-cycle revision from generic forecast explanation, and frames changes as "what new information drove the revision." If fails: Fall back to the standard forecast explanation format and note that cycle-over-cycle attribution requires visibility into what inputs changed between runs.

</Workflow - Compare Forecast Cycles>

<Template - Executive Explainer>

# Forecast Explainer: {{sku_or_category}}

**Period:** {{time_period}}
**Prepared for:** {{audience}}
**Date:** {{today}}

---

## The Bottom Line

{{one_sentence_summary}}

## What Changed

| Metric | Previous | Current | Change |
|--------|----------|---------|--------|
| Point Forecast | {{prev_value}} | {{curr_value}} | {{delta}} ({{delta_pct}}%) |
| Upper Bound ({{confidence_level}}) | {{prev_upper}} | {{curr_upper}} | {{upper_delta}} |
| Lower Bound ({{confidence_level}}) | {{prev_lower}} | {{curr_lower}} | {{lower_delta}} |

## Why It Changed (Ranked by Impact)

1. **{{driver_1_name}}**: {{driver_1_explanation}}
   - Contribution: ~{{driver_1_magnitude}} units ({{driver_1_pct}}% of total change)

2. **{{driver_2_name}}**: {{driver_2_explanation}}
   - Contribution: ~{{driver_2_magnitude}} units ({{driver_2_pct}}% of total change)

3. **{{driver_3_name}}**: {{driver_3_explanation}}
   - Contribution: ~{{driver_3_magnitude}} units ({{driver_3_pct}}% of total change)

## What the Confidence Band Means

{{confidence_narrative}}

## Recommended Action

{{recommendation}}

---
*Source: {{data_source}} | Model: {{model_name_if_known}} | Generated by Demand Forecast Explainer*

</Template - Executive Explainer>

<Template - Technical Explainer>

# Forecast Technical Breakdown: {{sku_or_category}}

**Period:** {{time_period}}
**Audience:** Demand Planning Team
**Date:** {{today}}

---

## Summary Statistics

| Metric | Value |
|--------|-------|
| Point Forecast (mean) | {{point_forecast}} |
| Confidence Level | {{confidence_level}} |
| Lower Bound | {{lower_bound}} |
| Upper Bound | {{upper_bound}} |
| Band Width | {{band_width}} ({{band_width_pct}}% of point) |
| Prior Cycle Forecast | {{prior_forecast}} |
| Revision | {{revision}} ({{revision_pct}}%) |
| Model | {{model_name}} |
| Last Trained | {{last_trained_date}} |

## Decomposition

### Seasonal Component
{{seasonal_detail}}

### Trend Component
{{trend_detail}}

### Promotional/Event Lift
{{promo_detail}}

### External Regressors
{{external_detail}}

### Residual / Unexplained
{{residual_detail}}

## Confidence Interval Detail

- **Interpretation:** {{ci_interpretation}}
- **Safety Stock Implication:** {{safety_stock_calc}}
- **Service Level Mapping:**
  - Plan to P50 (point forecast): {{service_at_p50}}% expected fill rate
  - Plan to P75: {{service_at_p75}}% expected fill rate
  - Plan to P90: {{service_at_p90}}% expected fill rate

## Recommended Actions

1. {{action_1}}
2. {{action_2}}
3. {{action_3}}

## Data Quality Notes

{{data_quality_notes}}

---
*Source: {{data_source}} | Model: {{model_name}} | Generated by Demand Forecast Explainer*

</Template - Technical Explainer>