cash_flow_forecasting v1.0.0

name: cash_flow_forecasting description: "Build and run a rolling 13-week cash forecast for a small business from bank, invoice, and bill data: direct-method worksheet, confirmed vs probable receipts, crunch week detection against a cash floor, weekly roll and variance routine, cash conversion cycle, and the levers to pull before cash runs short. Triggers on requests to forecast cash flow, build a 13-week forecast, find when cash runs out, fix a cash crunch, or set up a weekly cash review." metadata: { "includeInPrompt": true }

Cash Flow Forecasting

Purpose

Give a small business a week-by-week answer to one question: in which week does cash get tight, and what can still be done about it. The tool is a rolling 13-week forecast built on the direct method, meaning it tracks actual receipts and disbursements week by week instead of starting from net income. Thirteen weeks is one quarter: long enough to act on a problem, short enough that the payment data behind it stays real. A profitable business can still miss payroll, because profit is recorded when work is earned and cash moves when money changes hands. This forecast watches the cash.

Workflow

1. Gather the raw material. Pull the current cleared bank balance, open receivables with each customer's actual payment history, open payables and bills with due dates, payroll amounts and pay dates, rent, loan payments, tax calendars, and any annual or quarterly bills due in the next quarter. If the user has accounting software exports or bank CSVs, use those. Work from records, not recollection.

1. Set the floor. Agree a minimum cash balance before building anything. Build it from fixed obligations: one payroll cycle plus one month of rent and core subscriptions is a workable start. Context for why the floor matters: JPMorgan Chase Institute research (Cash is King, 2016) found the median US small business held 27 cash buffer days, a quarter of businesses held 13 days or fewer, and median employer businesses held 18 days. A floor the forecast can test against turns that fragility into a number the user controls.

1. Build the worksheet. Follow references/worksheet-spec.md. Rows are receipts grouped by source, disbursements grouped by category, then net, closing, floor, and headroom. Receipts sit in the week cash is expected to clear the bank based on how that customer actually pays, not the invoice date. Disbursements sit in the week funds leave the account. Split interest and principal on debt. Hunt for the lumpy rows people forget: quarterly tax estimates, annual insurance, inventory pre-buys, owner draws, annual software renewals.

1. Grade every receipt. Mark each receipt confirmed (signed, scheduled, reliable payer) or probable (pipeline, milestones, slow or new payers). Keep them on separate rows. Run two views with bin/forecast.py build: the base case counts probable receipts at a weight the user picks (0.5 is the default in the tool), and the committed-only view counts them at zero. The gap between the two views is the size of the bet on money that has not landed yet.

1. Find the crunch weeks. Any week whose closing balance falls below the floor is a crunch week. Report the first crunch week, the lowest closing balance and its week, and how many weeks sit below the floor, for both views. Use the sample data in assets/ and the walkthrough in references/crunch-week-examples.md to show the user what a crunch pattern looks like: lumpy outflows stacking in back to back weeks while receipts run at a normal pace.

1. Match levers to the gap. Work through references/levers.md in order: timing moves first (invoice on delivery, reminders, re-time payment runs inside agreed terms), then terms changes (deposits, shorter terms, supplier splits), then working capital, then financing arranged early. Name the specific lever, the week it has to happen by, and the dollar effect on the crunch week. A timing gap and a structural gap get different fixes: if disbursements beat receipts in most weeks, borrowing only moves the crunch later with interest added, and the honest advice is terms, pricing, and cost work.

1. Run the cash conversion cycle when the pattern repeats. bin/forecast.py ccc computes DIO, DSO, DPO, and CCC = DIO + DSO - DPO from average inventory, receivables, payables, COGS, and revenue. The CCC is how many days of operations the business funds out of its own cash. A crunch that returns every quarter usually lives here, not in any single week's timing.

1. Roll it every week. This step is the skill. Each week, on a fixed day: replace the finished week's forecast with bank actuals, run bin/forecast.py variance and split the differences into timing variance (money that landed in a different week) and real variance (money that grew, shrank, or vanished), fix the remaining weeks for real variance only, drop the finished week, add a new week 13, and re-check for crunch weeks. Ten minutes a week keeps the forecast honest. A forecast built once and never rolled is a snapshot, and it goes stale fast.

1. Report in plain numbers. Lead with the first crunch week and the lowest balance. Then the cause in one sentence, the levers chosen with their deadlines, and what changed since last week's roll. No narrative padding around a cash warning: if the forecast says week 7 breaks the floor, the report says that first.

Output Contract

• Every build produces: the worksheet or forecast CSV, opening balance and floor with the floor's components, the week-by-week table with receipts, disbursements, closing, and committed-only closing, the crunch week list for both views, and the first crunch week with its cause.
• Every lever recommendation states the dollar effect on the crunch week's closing balance and the week by which the lever must be pulled. Re-run the build with the lever applied and show the new lowest balance. Advice without a re-run number is an opinion, label it as one.
• Every weekly roll produces: the variance table for the finished week, the timing vs real split with the evidence for each call, the list of changes made to future weeks, and the updated crunch picture.
• Numbers reconcile: opening plus receipts minus disbursements equals closing for every week, and closing feeds the next week's opening. A table that does not tie out does not ship.

Operating Rules

• Cash timing only. Revenue counts when it clears the bank, costs count when funds leave. Never build the 13-week view from accrual profit figures.
• Confirmed and probable receipts never merge into one line, and probable money never carries a decision at face value. If the committed-only view goes negative, say so plainly.
• Place receipts by observed payment behavior per customer. A customer who pays 10 days past terms gets forecast that way until their behavior changes.
• Include every lumpy outflow inside the 13 weeks, in its actual week, at its full amount. Spreading an annual premium across months hides the exact week this forecast exists to find.
• Price any financing from the lender's written terms: rate, fees, term, and repayment shape. Never quote typical market rates as if they were the user's offer.
• Do not invent receipts, payment histories, or balances to complete a template. Missing data gets named as missing, and the forecast carries a note saying which weeks it weakens.
• The user's floor, probable weight, and payment behavior assumptions are stated in every output, so a reader can change one assumption and re-run instead of arguing with a hidden one.