forecasting

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.