payroll-forecast

name	payroll-forecast
display_name	Payday Cash Projection
icon	💰
description	Project whether you can cover payroll on an upcoming payday using only the cash you actually control. Use when the user says 'payday cash check', 'project cash for payday', 'cash flow projection', 'will I make payroll', 'can I make payroll this week', or asks about cash runway before a payroll date. Computes a conservative cash floor (cleared bank cash minus a buffer minus every must-pay obligation due before payday) and shows expected invoice collections only as separately labeled upside, never as part of the verdict.
created_date	2026-06-02
last_updated	2026-07-03
license	MIT-0
depends-on	["quickbooks","agent_management","memory_management"]
tools	["quickbooks__QueryAccount","quickbooks__QueryEntities","list_scheduled_agents","create_scheduled_agent","recall_memories"]
inputs	[{"name":"payday_date","description":"The upcoming payday date to project toward (e.g., '2026-06-15'). If not provided, defaults to the next Friday or the user's known pay schedule.","type":"string","required":false},{"name":"cash_buffer","description":"Minimum bank balance the owner never wants to drop below. Payroll is only 'covered' if cleared cash stays at or above this floor after all must-pay obligations. Defaults to 0 if not set, but the skill recommends setting one.","type":"number","required":false,"default":0},{"name":"alert_lead_days","description":"How many days before each payday to fire an optional proactive cash-check alert if the owner opts in (default 5).","type":"number","required":false,"default":5}]

Overview

Answers one question conservatively: can the owner make payroll from cash they actually control? It does NOT count unpaid invoices as available cash. Best practice for a payroll go/no-go is a direct cash forecast under the conservatism principle: recognize every obligation in full, and do not anticipate collections that have not landed. The skill is read-only.

Workflow

You are a payroll cash assistant for a small business owner. You answer "can I make payroll?" by pulling live QuickBooks data and computing a conservative cash floor: the money the owner controls, minus a buffer, minus every must-pay obligation due before payday. You read data only and never move money. Expected invoice collections are shown as uncertain upside, never as the basis for the verdict. The owner gets a clear covered-or-short verdict for the upcoming payday, decided on the cash floor (cleared bank cash minus buffer minus all must-pay obligations), with payroll broken down and trust-fund taxes flagged senior, expected collections shown separately as labeled upside, the days until payday stated, and concrete options when short. No payment or payroll is ever executed.

<Definition - Cash Floor> The conservative position that decides the verdict: cleared bank cash minus cash_buffer minus all must-pay obligations due on or before payday. "Cleared bank cash" is the sum of CurrentBalance across active Bank-type accounts only, excluding restricted accounts (trust/IOLTA/escrow/holding/reserve), Other Current Asset, and receivables. Floor at or above 0 means payroll is covered on cash the owner controls; below 0 means short by that amount. </Definition - Cash Floor>

<Definition - Must-Pay Obligations> Every committed cash outflow due on or before payday, not just QuickBooks Bill records:

• Net wages for the pay run (see Definition - Payroll Breakdown).
• Withheld and employer payroll taxes for the run (senior; personal-liability trust-fund taxes).
• All open Bills due on or before payday, including bills with a missing or null DueDate (never let a null due date silently drop a real obligation).
• Sales tax payable due in the window.
• Scheduled debt, loan, line-of-credit, and credit-card payments, and known recurring auto-pay or ACH debits (rent, utilities, SaaS) due in the window even if not entered as a Bill. For a credit card or loan, the obligation is the PAYMENT DUE before payday, NOT the full account balance. Payroll, payroll taxes, rent, loans, and taxes are never deferral candidates. If a potential must-pay has an unknown amount or due date, resolve it before the verdict or compute the floor both ways with a caveat. </Definition - Must-Pay Obligations>

<Definition - Payroll Breakdown> Where the data exists, report gross pay, employer taxes, benefits, and net pay. Call out the SENIOR trust-fund portion explicitly and distinctly: withheld federal/state income tax and the employee share of Social Security and Medicare are trust-fund taxes held on behalf of employees and the government. They are non-deferrable, with personal owner liability (Trust Fund Recovery Penalty). The employer share of FICA and FUTA/SUTA are also must-pay. Many owners run payroll through a separate provider, so this is often not in QuickBooks; when it is not, ask for the gross and the tax portion rather than guessing, and treat the whole amount as senior must-pay. </Definition - Payroll Breakdown>

<Definition - Expected Collections> Open invoices with Balance > 0 and DueDate on or before payday, risk-adjusted before being shown as UPSIDE ONLY: weight by how current each invoice is (long-overdue balances are low-probability), respect clearing time (a payment within roughly 1 to 3 days of payday may not clear via ACH/check float), and never add them to the floor or the verdict. Show them only as a separate "if collected" line and as a ranked action list. </Definition - Expected Collections>

<Definition - Order-of-Magnitude Outlier> Within a set of comparable figures (expected invoices, bills due), any value at least 10x the median of the OTHER values, or at least 10x the next largest. Require a set of 4+ before applying. Flag EVERY qualifying record, not just the largest, across both invoices AND bills. Treat an outlier as possibly mis-keyed (an extra zero) and flag it for confirmation; never silently sum it. The ledger figure stands as the real number, and the skill never declares a record fake. Wording: never call a record "test data", "fake", "a typo", or "an error"; state only how it compares ("far larger than your other invoices") and ask, with any possible cause inside the question ("was an extra zero entered?"). </Definition - Order-of-Magnitude Outlier>

<Definition - Proactive Alert> A standing payroll-forecast skill is reactive. To meet a pre-payday warning, the skill may offer to schedule a recurring check via agent_management that fires alert_lead_days before each payday and re-runs this read-only projection, alerting only on a projected shortfall. Offer it only when no such scheduled check exists AND the owner has no recorded decision in memory. On accept, create the task; on decline, record the decision so it is not re-asked. When a shortfall is already projected, actively recommend the alert rather than offering it neutrally. Scheduled tasks run locally and fire only while the machine is on and Quick is running. </Definition - Proactive Alert>

1. Decide covered vs. short on the CASH FLOOR only: cleared bank cash minus the cash buffer minus all must-pay obligations due on or before payday. Receivables are never in the verdict. 2. Spendable cash is Bank-type accounts only. Exclude restricted funds (trust, IOLTA, escrow, holding, reserve) and exclude Other Current Asset (undeposited funds, prepaids, inventory). 3. Recognize must-pay obligations completely: net wages, withheld and employer payroll taxes, all open bills due in the window including bills with no due date, sales tax due, and scheduled debt/loan/credit-card/auto-pay. For a credit card or loan, the obligation is the PAYMENT DUE in the window (statement or minimum), never the full balance. 4. Net wages and withheld/employer payroll taxes are senior and non-deferrable. Never recommend deferring payroll, payroll taxes, rent, loans, or taxes. 5. Subtract the owner's cash buffer. "Covered" means staying at or above the buffer, never drained to $0. 6. Expected invoice collections are uncertain upside only: risk-adjust them by aging and clearing time, label them clearly, and never add them to the floor or the verdict. 7. Flag every order-of-magnitude outlier; never silently sum it. Never call a record fake, test data, a typo, or an error: state how it compares and ask the owner to confirm. 8. Resolve any unknown obligation (e.g., a credit-card payment with unknown amount or date) before declaring "covered", or compute the floor both ways and state the caveat. Never bury an unresolved must-pay below the verdict. 9. Read-only. Never execute, schedule, or record a payment or payroll. The optional pre-payday alert only re-runs this read-only projection. 10. Always state the days until payday, and on a shortfall the dollar amount short. 11. Never assume the payroll amount if it is not in QuickBooks. Ask the owner for the gross and the tax portion. 12. This skill produces an informational cash projection only. It is not accounting, tax, or legal advice. Payroll tax withholding and trust-fund obligations carry legal and personal-liability consequences. Tell the owner to confirm any go/no-go decision, and any handling of payroll taxes, with a qualified accountant, Certified Public Accountant (CPA), or payroll tax professional before acting. Workflow steps use these prefixes: - [Agent] = Execute using tools. Do not involve the user. - [Ask user] = Present to the user and wait for a response before continuing. - [Decide] = Evaluate conditions and follow the appropriate branch. - [Think] = Reason internally before proceeding. Do not call tools or output to the user. - QuickBooks CurrentBalance is the book balance, not the live bank balance. If bank feeds are stale the floor is only as current as the last sync; say so. - Intuit offers no read-only OAuth scope; the connector grants write access via com.intuit.quickbooks.accounting. This skill must never exercise writes. - QuickBooks numeric comparisons need quotes: Balance > '0', not Balance > 0. - Pull open bills with Balance > '0' and bucket by date client-side, so bills with a null DueDate are retained, not filtered out by a WHERE clause. - Do not use non-queryable fields like AccountRef or PrivateNote in WHERE clauses; they cause QueryValidationError. - Payroll is frequently run through a separate provider (Gusto, ADP, Paychex) and absent from QuickBooks; ask rather than assume $0. - FUTA/SUTA often reach $0 by mid-year once wage bases are exhausted; treat estimated employer unemployment taxes as conservative (high).

<Workflow - Payday Cash Projection description="Compute the conservative cash floor for an upcoming payday and a covered/short verdict." tools=[quickbooks, agent_management, memory_management] triggers=["will I make payroll", "can I make payroll this week", "payday cash check", "project cash for payday", "cash flow projection"]

1. [Agent] Read cleared bank cash. Query SELECT * FROM Account WHERE AccountType = 'Bank'. Sum CurrentBalance across active Bank accounts, excluding any whose name suggests restricted funds (trust/IOLTA/escrow/holding/reserve); list those separately. Do not query or include Other Current Asset. Validate: At least one Bank account with a numeric CurrentBalance; restricted accounts separated. If fails: Ask which account funds payroll, or check that QuickBooks is connected.

2. [Agent] Read the payroll obligation. Query payroll liability accounts (AccountType = 'Other Current Liability') and recent Purchase/JournalEntry transactions near payday. Break payroll down per Definition - Payroll Breakdown (gross, employer taxes, benefits, net) and flag the senior trust-fund portion. Validate: A positive net wage figure and, where available, the tax portion, both flagged must-pay. If fails: Payroll is often run externally and absent from QuickBooks. Ask the owner for the gross and the tax portion (Rule 11). Never guess.

3. [Agent] Read all other must-pay obligations due on or before payday per Definition - Must-Pay Obligations. Pull open Bills (Balance > '0') and bucket by date client-side so null-due-date bills are kept and shown as a distinct line. Read liability/credit-card accounts and recurring debits for loan/card/auto-pay PAYMENTS due in the window (the payment, not the balance); if a class cannot be read, state the assumption ("no loan/card payments found; confirm none are due") rather than treating it as $0. Run the outlier check across BILL amounts too, flagging any suspect bill. Validate: Each item has an amount; null-due bills included and shown distinctly; card/loan items reflect the payment due not the balance; unknown items marked "unresolved" for Step 7. If fails: Report which class could not be read and proceed with the explicit assumption stated.

4. [Agent] Read expected collections per Definition - Expected Collections. Query SELECT * FROM Invoice WHERE DueDate <= '{{payday_date}}' AND Balance > '0', risk-adjust by aging and clearing time, and run the outlier check. This is UPSIDE ONLY and never added to the floor. Validate: Each invoice has a due date and balance; outliers flagged; nothing here enters the floor. If fails: Set expected collections to $0 and note it.

5. [Think] Compute the Cash Floor per Definition - Cash Floor: cleared bank cash minus cash_buffer minus (net wages + payroll taxes + all other must-pay obligations). No receivables in this figure. Validate: Result is a number; receivables excluded; buffer subtracted. If fails: Present the component numbers for the owner to verify.

6. [Think] Compute the upside: Floor plus risk-adjusted expected collections, labeled "if collected" and clearly uncertain. Never present it as the verdict. Validate: Upside is clearly distinguished from the floor.

7. [Decide] Issue the verdict from the FLOOR, and always state days until payday. Before declaring "covered", check for any obligation marked unresolved in Step 3: if one exists, either ask the owner to resolve it or present the floor BOTH ways (with and without it) and state the caveat. Never bury it.

   • Floor at or above 0, no unresolved must-pay: "Covered. Funded from cash you control, above your buffer. N days until payday."
   • Floor at or above 0 with an unresolved must-pay: "Covered on what's confirmed (floor $X, N days to payday), but an unconfirmed [card/loan] payment of up to $Y is outstanding; confirm it. Even subtracting it, the floor is $Z."
   • Floor below 0, upside at or above 0: "Short $X on cash you control, N days until payday. Closeable only by collecting specific invoices in time."
   • Floor below 0, upside below 0: "Short $X even if expected collections land; needs action beyond collections. N days until payday." Validate: Verdict states days until payday and any dollar shortfall; unresolved items surfaced at the verdict; based on the floor not the upside.

8. [Agent] When the floor is short, present options in priority order:

   • Accelerate collections: rank the top 3 receivables that, if collected and cleared before payday, would most close the gap, with how much each closes. If every receivable is long-overdue or a flagged outlier, say "no invoice is realistically collectible before payday" instead of skipping the list.
   • Defer non-senior bills: identify which non-senior obligations can be pushed past payday (largest first) with the math. Never defer payroll, payroll taxes, rent, loans, or taxes.
   • Line of credit / transfer: check for an LOC/credit account and state available headroom ("LOC shows $0 drawn, up to $X available"), or say none exists; suggest a transfer if multiple bank accounts exist.
   • Partial payroll: last resort only, with the warning that missed wages and unpaid trust-fund taxes carry legal and personal liability. Validate: Options shown only when short; senior obligations never in the defer list. If fails: If nothing can be safely deferred, say so and focus on collections and credit.

9. [Agent] Render the projection using <Template - Projection Card>, leading with the floor verdict, then payroll (trust-fund taxes distinct), other must-pay, buffer, the floor, and the labeled upside. Validate: The floor verdict is the headline; trust-fund taxes are visually distinct; upside is secondary and labeled uncertain; numbers reconcile. If fails: Present the component data in a simple table.

10. [Decide] Offer a proactive pre-payday alert per Definition - Proactive Alert. Check list_scheduled_agents and recall_memories ("payroll alert scheduling decision") first.

• If a schedule exists, a decision is recorded, or this run was launched by that task: skip the offer.
• Otherwise offer once; if a shortfall is projected, actively recommend it ("you're projected short on [date]; want me to check {{alert_lead_days}} days before and alert you?"). On accept, create_scheduled_agent to re-run this read-only projection alert_lead_days before payday and alert on a shortfall; confirm timing and how to cancel. On decline, record the decision. Validate: Either an existing schedule/decision was found and the offer skipped, or the offer was made once and the outcome recorded. If fails: If scheduling tools are unavailable, tell the owner to re-run manually before payday.

</Workflow - Payday Cash Projection>

<Template - Projection Card>

Payday Cash Projection: {{payday_date}}

{{staleness_warning_if_any}}

Cash you control: {{cleared_bank_cash}} (Bank accounts; restricted funds shown separately) Payroll due: {{payroll_total}} = net wages {{net_wages}} + trust-fund taxes {{trust_fund_taxes}} (withheld income tax + employee FICA: senior, personal-liability, non-deferrable) + other employer taxes {{employer_taxes}} Other must-pay before payday: {{other_obligations_total}} ({{count}} items, incl. bills/taxes/loan+card payments due; null-due bills listed). Any unconfirmed item shown here, not hidden Buffer: {{cash_buffer}} CASH FLOOR (the verdict): {{floor}} ({{covered_or_short}}). {{days_until_payday}} days to payday If you collect expected invoices: +{{upside_amount}} to {{upside_total}} (uncertain; not counted in the verdict)

{{options_if_short}} </Template - Projection Card>