Weekly forecast rollup

Weekly forecast rollup

Turns this week's and last week's opportunity exports into the numbers a forecast call needs, with every movement explained by deal. The script does the math. You check the inputs, read the result, and write the short narrative.

When to use

• Monday or Friday forecast prep, or before a board or leadership update.
• "Why did commit drop?" or "which deals slipped out of the quarter?"
• Not for setting quota or attainment math. This reports what the CRM says.

Inputs

1. This week's export in data/, for example data/opps-2026-11-04.csv. One row per opportunity, open and closed, for at least the period. Needed: an ID, amount, and close date. Strongly recommended: name, owner, team (or owner role or region), stage, forecast category.
2. Last week's export with the same columns. Suggest the user saves each week's export with the date in the file name so next week's comparison is free.
3. The period: usually the current quarter. Ask if unclear.

Columns are matched by common names (Salesforce: Opportunity ID, Opportunity Owner, Forecast Category; HubSpot: Record ID, Deal owner, Forecast category, Deal Stage). If a column has another name, pass --map field=Column Name (fields: id, name, owner, team, amount, close_date, stage, forecast_category).

Steps

1. Find the two most recent exports in data/. Confirm the dates and period with the user.

2. Run:

   node scripts/forecast-rollup.mjs data/opps-2026-11-04.csv data/opps-2026-10-28.csv --period-start 2026-10-01 --period-end 2026-12-31 --out out --name forecast-2026-11-04

3. Read out/<name>.json. Check data_problems first. Many deals with no forecast category or unreadable dates mean the numbers are not trustworthy yet; say so before anything else.
4. Write the narrative in 5 bullets or fewer: where forecast landed, the biggest movement and why (by deal), what slipped out of the period, any rep whose commit dropped, and the 2 or 3 deals to discuss on the call.
5. Show the narrative, then the "By rep" table from out/<name>.md.

Category rules

• Closed won counts by stage (Closed Won) or category Closed. Closed lost and Omitted are left out of every total.
• Forecast = closed won + commit. Upside = forecast + best case. Pipeline is reported on its own.
• A deal with no category counts as pipeline and is listed in data_problems.
• A deal in last week's export but not this week's is "dropped": deleted, merged, or filtered out of the view. Ask the user which.

Output to the user

**Q4 forecast: $177,000 (+$32,000 WoW).** Upside $237,000. Pipeline in period $0.

- Northwind Traders ($50,000) closed won; Adventure Works ($40,000) moved to commit.
- Contoso Robotics ($30,000) slipped to 2027-01-15, out of the quarter.
- Fabrikam Health commit cut by $8,000 to $72,000.
- Tailspin Toys lost; Proseware dropped from the export (check if deleted).
- Discuss: Contoso slip reason, Fabrikam discount, Wide World Importers next step.

Guardrails

• Report what the exports say. Never move a deal between categories yourself; suggest it as a question for the rep.
• Do not write back to the CRM.
• Amounts are summed as given. If the export mixes currencies, stop and ask for a converted amount column.

Weekly forecast rollup

Turns this week's and last week's opportunity exports into a forecast by rep and team, plus a list of every deal that moved: slipped, pulled in, upgraded, downgraded, new, won, lost, or dropped. Ready for the Monday forecast call in a minute.

Who it is for

RevOps, sales managers, and founders who run a weekly forecast from HubSpot, Salesforce, or any CRM that exports CSV.

Example

Input: examples/opps-2026-11-04.csv and examples/opps-2026-10-28.csv, period 2026-10-01 to 2026-12-31.

Output (out/forecast.md):

Closed won $65,000 | Commit $112,000 | Forecast $177,000 | Best case $60,000 | Upside $237,000
Week over week: forecast +$32,000, best case -$10,000, pipeline -$45,000.
Slipped: Contoso Robotics: new logo (Rep A, $30,000): 2026-12-10 to 2027-01-15, OUT OF PERIOD
Upgraded: Adventure Works (Rep C, $40,000): best_case to commit
Amount changed: Fabrikam Health (Rep B): -$8,000

Plus tables by team and by rep, and a JSON file with everything.

What it can access

• Runs node scripts/forecast-rollup.mjs (Node built-ins only, no network).
• Reads data/ (plus the kit's own examples/), writes out/.

Setup

None. Each week, export your opportunities to data/ with the date in the file name.