Forecasting

<!-- Copyright 2026 Anthropic PBC -->

<!-- SPDX-License-Identifier: Apache-2.0 -->

Demand Forecasting

Forecasting has two paths. Pick the right one — using a subagent when you don't need one wastes turns; skipping it when you do gives you a bad number.

Path A — compute it yourself (code execution)

Use this when all of the following hold:

• horizon ≤ 14 days
• the product's is_seasonal flag is 0
• the product's promo_next_month flag is 0
• the task doesn't mention a promo, holiday, or trend change

Then the forecast is just a rolling mean. This skill ships a script for it:

python .claude/skills/forecasting/rolling_mean.py SKU-0057 14

That's it — one Bash call, ~200 tokens, no subagent. Read the script if you

want to adapt it (it's ~20 lines).

Batch variant for sweeps: if you need days-of-cover for *many* SKUs at

once (e.g., the daily low-stock check), don't loop tool calls — run the

batch script:

python .claude/skills/forecasting/batch_days_of_cover.py 20

Returns the 20 most urgent SKUs as JSON, ranked by days-of-cover. This is

what replaces the 100+ get_stock_level / get_sales_velocity calls the

old agent made on F1.

Path B — spawn a forecaster subagent

Use this when any of the following hold:

• horizon > 14 days
• is_seasonal is 1
• promo_next_month is 1, or the task mentions a promo
• recent sales show a visible trend break

Why a subagent: the forecaster needs the full 90-day history in context to spot seasonality and promo effects. That's ~90 rows × however many SKUs. Loading that into *your* context crowds out the rest of the task. A subagent gets its own context window, does the analysis there, and hands back a small JSON.

How: Delegate to the forecaster callable agent. Send it just the SKU,

product flags, and horizon — not the history rows. The forecaster has

Bash access to the same /mnt/user/data/ and will compute over the full

history in its own context (that's the point: the 90 rows live there, not

here). It returns {forecast_qty, confidence, method, flags} JSON —

parse it strictly; if the JSON is malformed that's an error, not

something to guess around.

If callable_agents isn't available (it's a research-preview feature),

fall back to computing the rolling-mean inline yourself and set

confidence ≤ 0.55 so the reorder-policy skill escalates to human review

instead of auto-ordering on a number you couldn't validate.

Seasonal calendar (sanity-check your numbers)

Outdoor gear is highly seasonal. When the horizon crosses a boundary, the

rolling mean lags the turn — lean on Path B and mention the season.

| Window | Categories that lift | Expect vs baseline |

|---|---|---|

| Mar–May | Footwear, packs, rain shells, trekking poles | 1.3–1.6× |

| Jun–Aug | Tents, sleeping, stoves, water filtration | 1.5–2.0× (peak quarter) |

| Sep–Oct | Insulated apparel, optics, headlamps | lift; tents/footwear taper |

| Nov–Dec | Giftable price points; heaviest promo | confirm promo flags |

| Jan–Feb | Reset — lowest volume | good for cycle counts |

Promotional handling

Promos are the most common cause of under-ordering. When promo_next_month=1

or the task mentions a promo:

• Do not rely on rolling-mean alone — that's pre-promo demand.
• Look for a historical analog (same SKU, comparable promo in the last 12

months) and use *that* uplift. If none exists, the subagent should set

flags: ["promo_uplift_uncertain"] and a confidence well under 0.6.

• Default to flag-for-review over auto-order when lift is uncertain.

Over-ordering on a promo is recoverable; under-ordering is a stockout

during peak attention.

• If the promo end date is known, account for the post-promo dip — don't

leave the channel overstocked the week after.

The failure mode to avoid: stating the lift in prose ("could be ~3×")

while the forecast_qty you return is still the un-lifted baseline mean.

Anchor the *number*, not just the narrative.

What to do with the result

Feed {forecast_qty, confidence, flags} into the reorder-policy skill. In particular: if confidence < 0.6, reorder-policy says escalate, don't auto-order. Do not drop the confidence or flags on the floor — they're part of the contract.

Worked example (Path B)

Task: "Reorder SKU-0091 for next month's promo." → promo_next_month=1, horizon=30 → Path B.

Subagent returns: {"forecast_qty": 2100, "confidence": 0.41, "method": "baseline_mean_no_comparable_promo", "flags": ["promo_uplift_uncertain"]}

confidence 0.41 < 0.6 → per reorder-policy, do not create a PO. Escalate via notify-templates with the flags, recommend ~2,100 baseline + note that promo uplift could be 2-3× and needs a human call.