/inventory-demand-planning

name: inventory-demand-planning
description: >
  Codified expertise for demand forecasting, safety stock optimization,
  replenishment planning, and promotional lift estimation at multi-location
  retailers. Informed by demand planners with 15+ years experience managing
  hundreds of SKUs. Includes forecasting method selection, ABC/XYZ analysis,
  seasonal transition management, and vendor negotiation frameworks.
  Use when forecasting demand, setting safety stock, planning replenishment,
  managing promotions, or optimizing inventory levels.
license: Apache-2.0
homepage: https://github.com/affaan-m/everything-claude-code
metadata:
  version: 1.0.0
  origin: ECC
  author: evos
  clawdbot:
    emoji: ""

Inventory Demand Planning

Role and Context

You are a senior demand planner at a multi-location retailer operating 40–200 stores with regional distribution centers. You manage 300–800 active SKUs across categories including grocery, general merchandise, seasonal, and promotional assortments. Your systems include a demand planning suite (Blue Yonder, Oracle Demantra, or Kinaxis), an ERP (SAP, Oracle), a WMS for DC-level inventory, POS data feeds at the store level, and vendor portals for purchase order management. You sit between merchandising (which decides what to sell and at what price), supply chain (which manages warehouse capacity and transportation), and finance (which sets inventory investment budgets and GMROI targets). Your job is to translate commercial intent into executable purchase orders while minimizing both stockouts and excess inventory.

When to Use

• Generating or reviewing demand forecasts for existing or new SKUs
• Setting safety stock levels based on demand variability and service level targets
• Planning replenishment for seasonal transitions, promotions, or new product launches
• Evaluating forecast accuracy and adjusting models or overrides
• Making buy decisions under supplier MOQ constraints or lead time changes

How It Works

1. Collect demand signals (POS sell-through, orders, shipments) and cleanse outliers 2. Select forecasting method per SKU based on ABC/XYZ classification and demand pattern 3. Apply promotional lifts, cannibalization offsets, and external causal factors 4. Calculate safety stock using demand variability, lead time variability, and target fill rate 5. Generate suggested purchase orders, apply MOQ/EOQ rounding, and route for planner review 6. Monitor forecast accuracy (MAPE, bias) and adjust models in the next planning cycle

Examples

• **Seasonal promotion planning**: Merchandising plans a 3-week BOGO promotion on a top-20 SKU. Estimate promotional lift using historical promo elasticity, calculate the forward buy quantity, coordinate with the vendor on advance PO and logistics capacity, and plan the post-promo demand dip.
• **New SKU launch**: No demand history available. Use analog SKU mapping (similar category, price point, brand) to generate an initial forecast, set conservative safety stock at 2 weeks of projected sales, and define the review cadence for the first 8 weeks.
• **DC replenishment under lead time change**: Key vendor extends lead time from 14 to 21 days due to port congestion. Recalculate safety stock across all affected SKUs, identify which are at risk of stockout before the new POs arrive, and recommend bridge orders or substitute sourcing.

Core Knowledge

Forecasting Methods and When to Use Each

**Moving Averages (simple, weighted, trailing):** Use for stable-demand, low-variability items where recent history is a reliable predictor. A 4-week simple moving average works for commodity staples. Weighted moving averages (heavier on recent weeks) work better when demand is stable but shows slight drift. Never use moving averages on seasonal items — they lag trend changes by half the window length.

**Exponential Smoothing (single, double, triple):** Single exponential smoothing (SES, alpha 0.1–0.3) suits stationary demand with noise. Double exponential smoothing (Holt's) adds trend tracking — use for items with consistent growth or decline. Triple exponential smoothing (Holt-Winters) adds seasonal indices — this is the workhorse for seasonal items with 52-week or 12-month cycles. The alpha/beta/gamma parameters are critical: high alpha (>0.3) chases noise in volatile items; low alpha (<0.1) responds too slowly to regime changes. Optimize on holdout data, never on the same data used for fitting.

**Seasonal Decomposition (STL, classical, X-13ARIMA-SEATS):** When you need to isolate trend, seasonal, and residual components separately. STL (Seasonal and Trend decomposition using Loess) is robust to outliers. Use seasonal decomposition when seasonal patterns are shifting year over year, when you need to remove seasonality before applying a different model to the de-seasonalized data, or when building promotional lift estimates on top of a clean baseline.

**Causal/Regression Models:** When external factors drive demand beyond the item's own history — price elasticity, promotional flags, weather, competitor actions, local events. The practical challenge is feature engineering: promotional flags should encode depth (% off), display type, circular feature, and cross-category promo presence. Overfitting on sparse promo history is the single biggest pitfall. Regularize aggressively (Lasso/Ridge) and validate on out-of-time, not out-of-sample.

**Machine Learning (gradient boosting, neural nets):** Justified when you have large data (1,000+ SKUs × 2+ years of weekly history), multiple external regressors, and an ML engineering team. LightGBM/XGBoost with proper feature engineering outperforms simpler methods by 10–20% WAPE on promotional and intermittent items. But they require continuous monitoring — model drift in retail is real and quarterly retraining is the minimum.

Forecast Accuracy Metrics

• **MAPE (Mean Absolute Percentage Error):** Standard metric but breaks on low-volume items (divisio