Library/Builder Teardown

Teardown: A CPG Demand Forecasting Model

How 90%+ forecast accuracy actually gets built: the censored-demand problem that corrupts every naive training set, hierarchy reconciliation, and why the promo calendar is half the model. Public excerpt; the full teardown lives in the Builder library.

The model, in four decisions

Our CPG forecasting builds target 90%+ accuracy, and the path there is mostly data decisions, not model decisions. The algorithm matters less than what you feed it and how you score it — four decisions carry the build.

Decision 1 — You're forecasting demand, but you recorded sales. The foundational trap of the entire field: sales history is censored demand. Every stockout week records low sales precisely when demand outran supply — so a naive model learns that your best weeks are slow weeks and helpfully forecasts you into the next stockout. Before any training, stockout periods must be identified (from inventory records joined to sales) and the demand behind them reconstructed or masked. This one correction does more for accuracy than any modeling choice you will make.

Decision 2 — The promo calendar is a first-class input. Promotions, price changes, and distribution gains produce spikes that are neither seasonality nor noise — they're caused, and the causes are known in advance. A model without the promo calendar learns blurred seasonality contaminated by past promos, then misses future ones entirely. Getting the historical promo calendar assembled — often from trade-spend records and tribal memory — is unglamorous and non-optional.

Decision 3 — Forecast the hierarchy, reconcile explicitly. Demand planning needs numbers at several grains at once — SKU, SKU-by-channel, category, total — and independent forecasts at each grain won't sum. Pick a reconciliation approach and make coherence a property of the system, because the planning meeting where SKU forecasts don't add up to the category forecast is the meeting where the model loses the room.

Decision 4 — Score it the way the business bleeds. Symmetric accuracy metrics treat over- and under-forecasting as equal sins. The business doesn't: under-forecasting the hero SKU costs stockouts in your best week; over-forecasting the long tail buries capital in dead inventory. Evaluation weights errors by their actual cost profile per SKU class — which changes model selection, and sometimes changes it a lot.

Where the first version broke

The model predicted the past's supply problems. Early validation looked strong until one quarter's forecast confidently dipped for a hero SKU — echoing a stockout from the prior year that the training data recorded as soft demand. Censoring correction (Decision 1) existed as a concept in the plan and hadn't been applied to that SKU's history. The rule since: stockout masking is verified per SKU before training, not assumed done, because the failure mode is silent and self-fulfilling.

A distribution gain read as organic lift. A retailer added the brand to hundreds of new doors mid-history; the model read the step-change as demand growth and extrapolated it. Distribution (doors, velocity per door) entered the feature set as its own signal, separating "more places to buy" from "more wanting to buy" — a distinction every CPG forecast lives or dies on.


The full teardown — the stockout-reconstruction methods, the promo-calendar assembly playbook, the reconciliation approach comparison, and the cost-weighted evaluation template — lives in the Builder library.

The Full Teardown Is in the Builder Library

Implementation detail, checklists, and the parts we'd rather not have public — for members.

Unlock with Builder