Purpose
Turn raw demand history and scattered market signals into a clear, defensible interpretation of what demand is actually doing — separating seasonality, underlying trend, and one-off anomalies — and delivering an adjusted demand view with explicit confidence levels so planners know how much to trust each signal before committing to a forecast.
When to Use
Invoke this skill when the user asks to:
- Interpret demand patterns or decompose a product's demand history
- Diagnose why a forecast missed and whether it was a signal or noise
- Identify seasonality, trend shifts, or anomalies in a SKU or category
- Sense near-term demand changes from promotions, pricing, or market events
- Prepare a demand signal summary for an S&OP or demand review meeting
- Reconcile statistical patterns with qualitative field or sales intelligence
Inputs Required
Before starting, collect:
- Product or category scope: The SKU, product family, or category being analyzed
- Demand history: Historical demand by period (weekly or monthly), ideally 18–36 months — shipments, orders, or POS/sell-through (note which)
- History granularity and horizon: Time bucket used and how far forward the interpretation must serve
- Market signals: Any known qualitative or leading indicators — promotions, price changes, competitor moves, new listings, macro trends, weather, campaigns
- External data inputs: Any available external series (category demand, search trends, economic indicators, channel data)
- Known events: Stockouts, one-time bulk orders, data errors, channel shifts, or supply disruptions that distort history
- Planning objective: What decision this feeds — forecast override, safety stock, buy quantity, or executive review
If granularity or horizon is missing, default to monthly buckets and a 6-month forward interpretation, and state the assumption.
Instructions
Step 1: Data Integrity Check
Before interpreting anything, validate the history is usable.
- Flag periods affected by stockouts (censored demand — actual demand exceeded what shipped)
- Flag one-time distortions: bulk orders, channel loads, returns, data errors, duplicate entries
- Note structural breaks: new product introductions, discontinuations, channel or customer additions, list price resets
- State whether the series measures true demand (orders/POS) or constrained supply (shipments) — this changes everything downstream
- Recommend cleansing actions (e.g., "impute stockout months to trend + seasonality") before decomposition
Step 2: Time-Series Decomposition
Separate the signal into its components.
- Level (baseline): The de-seasonalized, de-trended average demand
- Trend: Direction and slope — flat, growing, declining, or inflecting. Quantify (e.g., "+3% per month over trailing 6 months" or "trend reversal from +2% to −4% around period X")
- Seasonality: Identify recurring patterns and estimate seasonal indices per period (e.g., "December runs 1.6x baseline; February 0.7x"). Distinguish true seasonality (repeats across ≥2 cycles) from a one-time spike
- Residual/noise: What's left after level, trend, and seasonality — high residual variance means low predictability
- State the decomposition method assumption (additive vs. multiplicative) and why
Step 3: Anomaly Identification
Isolate points that don't fit the pattern.
- Classify each anomaly as: promotional lift, demand shock (external event), data artifact, supply-constrained (censored), or unexplained
- For each, estimate magnitude (% or units above/below expected) and whether it is repeating (a new pattern forming) or isolated (noise to exclude)
- Distinguish anomalies to remove from baseline vs. anomalies that signal a real shift and should be carried forward
Step 4: Qualitative Signal Integration (Demand Sensing)
Reconcile the statistics with market intelligence.
- Map each provided market signal to an expected demand effect: direction (up/down), magnitude (small/moderate/large), and timing (immediate/lagged/lead)
- Identify corroboration (qualitative signal confirms the statistical pattern → higher confidence) vs. conflict (field says growth, history says decline → flag for investigation)
- Weight leading indicators (search trends, competitor exits, pipeline) that the historical series cannot yet reflect
Step 5: Confidence Scoring
Assign an explicit confidence level to the overall interpretation and to each key signal.
- Use a High / Medium / Low scale with stated drivers:
- High: ≥2 full seasonal cycles, low residual variance, corroborating qualitative signals, clean data
- Medium: Partial history, moderate noise, or mixed qualitative signals
- Low: Short/dirty history, high residual variance, conflicting signals, or a structural break in progress
- Never present an interpretation without its confidence level and the top 2 reasons behind it
Step 6: Baseline vs. Adjusted Demand View
Produce the actionable output.
- Baseline: Statistical expectation from level + trend + seasonality, with anomalies removed
- Adjusted: Baseline modified for validated qualitative signals and forward events, with each adjustment itemized and justified
- Present as a period-by-period view (table) so the planner sees exactly where and why the adjusted view diverges from baseline
Step 7: Prioritized Planning Actions
Translate interpretation into decisions.
- List 4–6 actions ranked by impact and urgency (e.g., "raise Q4 forecast +12% for peak seasonality — High confidence"; "investigate conflicting field signal on SKU-X before overriding — Medium")
- Flag any signal needing more data before action, and specify exactly what data would resolve it
Output Format
- Structure: Seven sections following the analysis sequence; decomposition and baseline vs. adjusted views presented as tables; actions as a ranked list
- Length: 900–1,300 words
- Format: Structured document with tables for seasonal indices and the baseline-vs-adjusted period view; bullets and short prose elsewhere
- Sections: Data Integrity Check → Decomposition (level/trend/seasonality/residual) → Anomaly Identification → Qualitative Signal Integration → Confidence Scoring → Baseline vs. Adjusted Demand View → Prioritized Planning Actions
- Tone: Demand planning specialist — quantitative, cautious about noise, explicit about uncertainty, decision-oriented
Quality Checklist
Before delivering output, verify:
- [ ] Data integrity issues (stockouts, one-time orders, structural breaks) are flagged before any interpretation
- [ ] Seasonality is quantified with per-period indices, not described vaguely as "seasonal"
- [ ] Every anomaly is classified (promo / shock / artifact / censored / unexplained) and marked as isolated or repeating
- [ ] Each key signal and the overall interpretation carry an explicit High/Medium/Low confidence level with stated drivers
- [ ] Baseline vs. adjusted view is shown period-by-period with each adjustment itemized and justified
- [ ] Planning actions are ranked by impact and each carries its confidence level
Notes
- Shipments are not demand — if the series is constrained supply, say so and treat stockout periods as censored, or the trend will be understated
- Two full seasonal cycles is the practical minimum for trustworthy seasonal indices; with less, downgrade confidence and lean on category or analog data
- A conflict between statistical history and field intelligence is a finding, not a problem to smooth over — surface it and specify what would resolve it
- When history is short or noisy, a Medium-confidence adjusted view with a clear investigation action beats a falsely precise number
How to use this skill
This file is a Claude Code skill in Anthropic's standard format — markdown with YAML frontmatter at the top.
Installing in Claude Code:
~/.claude/skills/<folder-name>/SKILL.md— auto-loads in every session anywhere on your machine (recommended for skills you'll use across multiple projects)<your-project>/.claude/skills/<folder-name>/SKILL.md— auto-loads only when working in that project (recommended for project-specific skills)
Restart Claude Code or open a new session to register.
Using in Claude.ai, ChatGPT, Gemini, or other AI tools:
- Drag this file into a new chat, or copy and paste its contents
- Send your task or request as your next message — the AI will apply the skill where it fits
For Claude Code skill details: https://docs.anthropic.com/en/docs/claude-code/skills