Bill Pay Optimizer

Overview

Turns QuickBooks accounts payable into a prioritized pay-now-versus-defer plan that respects a minimum cash buffer, then hands the owner a ready-to-pay list to action themselves. It is read-only: it never moves money and never changes anything in QuickBooks.

Workflow

<Definition - Payment Terms> The SalesTermRef on a QuickBooks Bill encodes payment terms. "2/10 Net 30" means a 2 percent discount if paid within 10 days, otherwise the full amount is due in 30 days. "Net 30" means full amount due in 30 days with no discount. Measure the discount deadline from the bill/transaction date (TxnDate), not the due date: "2/10" means 10 days after the bill date. When a discount exists, show both the dollar savings and the annualized cost of skipping it - for 2/10 Net 30 that is roughly 36 percent APR (discount% / (100 - discount%) x 365 / (net days - discount days)) - so the owner sees why capturing it usually beats holding the cash. A missing term means no discount; default to the DueDate. </Definition - Payment Terms>

<Definition - Projected Cash Position> The decision basis is the position on cash the owner controls: total spendable cash minus total accounts payable due within the selected horizon. This before-inflows figure is what the pay-now-versus-defer plan and the buffer check are judged against. Expected incoming customer payments are NOT part of this figure. If the owner has known incoming payments in the window, you may show a separate, clearly-labeled "if collected" line (before-inflows position plus those inflows), but only after risk-adjusting them (an overdue invoice is less likely to land; a payment within ~1-3 days of need may not clear in time) and never let that optimistic figure drive which bills to pay. Lead with the before-inflows position; the after-inflows number is secondary and uncertain. </Definition - Projected Cash Position>

<Definition - Payment Priority> Recommend paying WITHIN terms, not early. A bill is "pay now" only if it is due within the next few days or carries an early-pay discount worth capturing; otherwise it "waits until its due date" - waiting until the due date is correct cash practice, not lateness. The order when cash is constrained: (1) bills with an early-pay discount still capturable (highest ROI), (2) bills due within ~3 days, (3) bills due in 4-7 days when cash is comfortable, (4) bills due later only if a discount applies or cash is ample, otherwise hold until their due date. Payroll, rent, loans, and taxes always sit in the must-pay group. Paying PAST a due date is a separate, flagged exception (see <Definition - Deferral Risk>), never part of normal prioritization. </Definition - Payment Priority>

<Definition - Deferral Risk> Distinguish two things: (a) waiting until a bill's due date to pay - normal, good cash practice, not a deferral; and (b) paying PAST the due date - a true deferral and an exception. Only (b) carries risk. When you recommend paying past due, you MUST quantify the cost (late fee, lost early-pay discount, or interest) and state the relationship risk: Low - large vendors unlikely to notice a short delay; Medium - subscriptions and utilities; High - small suppliers the business depends on, or any vendor whose terms impose late fees. When a group of bills is deferred together, also show a total estimated monthly cost of deferral (sum of late fees and interest across the group, even if approximate - e.g. "deferring these 108 bills likely costs roughly $X/month in late fees and interest"). Never recommend going past due just to free up cash unless a must-pay obligation or a buffer breach forces the tradeoff, and always show the cost so the owner decides. Payroll, rent, loans, and taxes are never candidates for going past due. </Definition - Deferral Risk>

<Definition - Order-of-Magnitude Outlier> Within the set of open bill amounts in this run, any bill at least 10x larger than the median of the OTHER bills, or at least 10x the next-largest. Baseline against the other bills, never the full set, so an outlier cannot inflate its own benchmark. Require a meaningful set first: with fewer than 4 bills, skip this check. Flag EVERY bill that qualifies, not just the biggest. An order-of-magnitude outlier is treated as likely mis-keyed (for example an extra zero) and is HELD out of the recommended Pay Now / ready-to-pay list until the owner confirms the amount, because recommending payment of a wildly wrong amount is harmful. The QuickBooks figure still stands as the real number: report it faithfully, never alter or drop it; holding it out of the recommendation is not the same as changing the books. Exclude a held outlier from the buffer/affordability math until confirmed, and state that you did. </Definition - Order-of-Magnitude Outlier>

<Definition - Must-Pay Obligations> Bills that are never deferral candidates: payroll, rent/lease, loan/mortgage payments, and taxes. Detect them three ways, not by guessing: (1) vendor name - payroll (ADP, Gusto, Paychex, Rippling, QuickBooks Payroll), rent/lease (property-management or landlord names), loans (banks, lenders, SBA), taxes (IRS, EFTPS, state department of revenue/franchise tax); (2) the QuickBooks account or category the bill posts to (Payroll, Rent, Loan/Note Payable, Taxes); and (3) keywords in the vendor or memo (payroll, wages, rent, lease, loan, mortgage, note, tax, withholding, 941, estimated tax). If a bill matches any of these, it sits in the must-pay group regardless of payment priority. If unsure, treat it as must-pay and confirm with the owner rather than silently deferring it. </Definition - Must-Pay Obligations>

<Definition - Duplicate Bill> Two or more open bills that look like the same obligation entered twice: same vendor and amount with the same or very close bill/due date, especially the same invoice/reference number (DocNumber); or an emailed vendor invoice that matches a bill already in QuickBooks. Duplicate payments are one of the most common and costly AP errors. Treat a suspected duplicate as HELD: surface it in "Needs Your Confirmation," keep both copies out of the recommended Pay Now list until the owner confirms which (if either) is real, and never silently merge or drop one - the owner resolves it in QuickBooks. Report the records faithfully; flagging a duplicate is not the same as deleting it. </Definition - Duplicate Bill>

<Workflow - Bill Pay Plan description="Pull open bills, optimize timing against cash, and prepare a ready-to-pay plan for the owner to action. Read-only: no payments, no QuickBooks writes." tools=[quickbooks, gmail, outlook, google-calendar, slack] triggers=["what bills do I need to pay", "what's due this week", "which bills can wait", "can I afford my bills", "optimize my payments", "bill pay", "vendor payments"]

1. [Agent] Confirm QuickBooks is connected and note which optional connectors (gmail, outlook, google-calendar, slack) are available. Record the QuickBooks last-sync timestamp. Validate: QuickBooks is connected and a sync timestamp is returned. If fails: Tell the owner "I can't pull your bills. QuickBooks appears disconnected. Please reconnect it in Settings." Stop.

2. [Decide] Is the QuickBooks last sync more than 4 hours ago? Validate: A clear yes/no is determined.

   • Yes: Set a staleness warning to lead the output.
   • No: Continue with no warning.

3. [Decide] Has the owner set a cash buffer for this session? Validate: {{cash_buffer}} has a value (provided or default).

   • Provided: Use it.
   • Default only: Note "using a default $5,000 buffer; tell me if you'd prefer a different floor" in the output.

4. [Agent] Query QuickBooks Bills with Balance > '0' and DueDate within {{horizon_days}} days, sorted by DueDate ascending. Capture vendor, amount, balance, due date, bill/transaction date, invoice/DocNumber, and SalesTermRef for each. Then classify every bill: tag must-pay obligations per <Definition - Must-Pay Obligations>; run the order-of-magnitude outlier check per <Definition - Order-of-Magnitude Outlier>; detect likely duplicates per <Definition - Duplicate Bill>; and apply any available vendor credit/credit memo to each bill's net payable. For the outlier-vs-must-pay overlap (Rule 10 exception): if a bill is both must-pay AND outlier, check whether the amount is consistent with other bills from the same vendor (same or similar amount month-to-month) - if consistent, clear the outlier hold and tag it as must-pay with a note; only keep the outlier hold on a must-pay bill when the amount is a spike vs. the established pattern. Validate: Query returns a list (empty is valid); each bill carries a must-pay flag, an outlier flag (cleared when the must-pay exception applies), a duplicate flag, and a net-payable amount after any vendor credit. If fails: Retry once. If still failing, tell the owner the bill list could not be retrieved and stop.

5. [Agent] Query QuickBooks for cash position: active Bank-type accounts only. Sum CurrentBalance for total spendable cash, excluding any Bank account whose name suggests restricted funds (trust, IOLTA, escrow, holding, reserve). Do NOT include Other Current Asset accounts (undeposited funds, prepaids, inventory are not spendable cash); if present, you may list their total separately but never inside spendable cash. Validate: At least one Bank account returned and the spendable-cash sum is a number; restricted and Other Current Asset balances excluded from the total. If fails: Retry once. If still failing, present bills with a clear warning that cash position is unavailable, and skip the optimization math.

6. [Agent] For each bill with a SalesTermRef encoding a discount per <Definition - Payment Terms>, calculate the discount amount and the deadline to capture it. Sort discount opportunities by savings descending. Validate: Each discount bill has a computed savings figure and deadline. If fails: Note which bills could not be parsed and treat them as no-discount.

7. [Agent] Compute the <Definition - Projected Cash Position> as the before-inflows position (spendable cash minus AP due in the horizon), excluding any held outlier per Rule 10. Email scan: if an email connector (gmail or outlook) is connected, you MUST scan the last {{horizon_days}} days for incoming vendor-invoice emails and match them to existing bills by vendor and amount; flag unmatched ones as "new, not in QuickBooks." ALWAYS report the scan status in the output ("scanned email, found N new invoice(s)" or "email not connected - skipped"); never silently skip it when a connector is present. If collected (optional upside): when the owner asks about incoming money, or to show the upside, query open customer invoices (receivables) due within the horizon and present them as a separate, clearly-labeled, risk-adjusted "if collected" line per <Definition - Projected Cash Position>. Never fold it into the before-inflows position that drives the plan. Validate: before-inflows position is a number; the email-scan status is reported; any "if collected" line is clearly separate and risk-adjusted. If fails: Present the before-inflows position from QuickBooks alone and note what was skipped.

8. [Think] Build the plan as pay-WITHIN-terms using <Definition - Payment Priority> and <Definition - Deferral Risk>. Keep every held outlier AND held duplicate (Rules 10, 12) OUT of all candidate schedules - they are neither pay-now nor wait until confirmed. "Pay now" means due within a few days or carrying a discount worth capturing; everything else "waits until its due date" (not late). Any recommendation to pay PAST a due date is a flagged exception with its cost shown. Generate three candidate schedules (aggressive pay-down, balanced, maximum-buffer-preservation), score each against and , and select the one that captures worthwhile discounts while keeping projected cash above {{cash_buffer}}. Confirm no must-pay obligation (per <Definition - Must-Pay Obligations>) is being pushed past due. Then proceed with the selected plan.

9. [Agent] Render the recommendation using <Template - Bill Plan>: a "Needs your confirmation" section listing any held outliers (far larger than your other bills, possibly a typo) AND likely duplicates (looks entered twice) with plain reasons; a Pay Now group with reasons (due soon or discount worth capturing); a Wait-Until-Due group, with any past-due exceptions flagged and their cost shown; a discount table showing savings and the annualized cost of skipping; the before-inflows projected balance (plus a separate "if collected" line when shown); a bills-only scope note; the email-scan status; and any new invoices found in email. Validate: Output shows the needs-confirmation section (or "none") covering outliers and duplicates, pay-now total, wait/defer total, before-inflows projected balance, buffer status, the bills-only note, and the email-scan status. If fails: Rebuild from available data; never present empty placeholders.

10. [Decide] Does the recommended Pay Now plan keep projected cash at or above {{cash_buffer}}? Validate: Projected balance compared against the buffer.

    • Yes: Present normally.
    • No: Flag the breach in the output and ask the owner whether to proceed anyway or adjust per Rule 2.

11. [Ask user] Present the plan and ask the owner to confirm it, adjust individual bills, change the buffer, or ask for reminders. Make clear this skill does not pay anything - confirming means "this plan looks right," and the owner pays through their own bank or each vendor's portal. Any held outlier bill is never in the recommended list; ask the owner to confirm the amount (or correct it in QuickBooks themselves) for each held bill individually. Wait for a decision. Validate: Owner confirms, edits, or declines; no held outlier sits in the recommended list without its own confirmation. If fails: Leave the plan presented and take no further action.

12. [Decide] Did the owner confirm the plan (or a subset) and want a handoff or reminders? Validate: A clear yes/no.

    • Yes: Continue to step 13.
    • No: Stop here. Leave the plan presented.

13. [Agent] Prepare the owner's handoff - NO money movement and NO QuickBooks writes:

    • produce a clear ready-to-pay list (vendor, amount, due date, and where/how the owner pays) they can action in their bank or each vendor's portal;
    • if a calendar or slack connector is available and the owner wants them, set reminders for confirmed and deferred bills 3 days before their due dates (reminders only, never payments);
    • never mark a bill paid or scheduled in QuickBooks, and never call any payment tool. Validate: a ready-to-pay list is produced; any reminders set are reminders only; no QuickBooks write or payment call was made. If fails: present the list as plain text the owner can copy.

14. [Agent] Report: the ready-to-pay list (count and total), deferred bills with any reminders set, held outliers still needing confirmation, and a clear closing note that no payments were made and nothing was changed in QuickBooks - the owner pays through their own bank or vendor portals. Validate: the output states that no money moved and nothing was written to QuickBooks. If fails: Re-summarize from the recommendation.

15. [Agent] MANDATORY bill-due alert check (per Rule 11 - do not skip, even if there were no bills this run). Decide whether to offer using two durable signals: (a) call agent_management list_scheduled_agents - does a daily bill-due watch already exist? (b) call recall_memories (query "Bill Pay Optimizer alert decision") - has the owner already accepted or declined? Validate: both signals are checked.

    • If a watch exists, OR a prior decision is recorded, OR this run was launched by the scheduled task: skip step 16.
    • Otherwise (no watch AND no recorded decision): continue to step 16.

16. [Ask user] Offer once, before ending: "Want me to watch your bills and alert you 3 days before anything is due, every morning at {{alert_time}}?"

    • If the owner declines: acknowledge and record the decision plainly so future runs do not re-ask (e.g. "Noted: the owner declined automatic bill-due alerts on the current date.").
    • If the owner accepts: create the watch with agent_management create_scheduled_agent - schedule_type "time_of_day", schedule_time {{alert_time}} (owner-local), no condition, tool_policy = read-only QuickBooks plus update_feed at importance "important"; prompt = check open bills and alert on any due within the next 3 days that are not yet scheduled for payment. Then confirm in plain language when and where it runs and how to cancel it (Settings, Scheduled tasks). The created schedule is the durable record of acceptance; step 15 detects it next time. Validate: either the decline was recorded, or a scheduled watch was created and confirmed. If fails: Report that the alert could not be set up, and leave the on-demand plan in place.

</Workflow - Bill Pay Plan>

<Template - Bill Plan>

# Bill Pay Plan - {{date}}

{{staleness_warning_if_any}}
{{buffer_note_if_default}}

## Spendable Cash
**{{spendable_cash}}** (Bank accounts only; restricted funds and non-cash assets excluded)

## Needs Your Confirmation
{{held_outliers_and_duplicates_or_none}}

## Pay Now ({{pay_now_total}})
{{pay_now_table}}

## Wait Until Due / Past-Due Exceptions ({{wait_total}})
{{wait_table_with_due_dates}}{{past_due_exceptions_with_cost_if_any}}

## Discount Opportunities
{{discount_table_with_savings_and_annualized_cost_or_none}}

## After Recommended Payments
- Starting spendable cash: {{spendable_cash}}
- Paying now: -{{pay_now_total}}
- **Projected balance (before incoming payments): {{projected_balance}}**
- If collected (risk-adjusted, does not drive this plan): {{if_collected_or_none}}
- Buffer status: {{above_or_below_buffer}}

## Email Scan
{{email_scan_status_and_new_invoices}}

<small>Scope: QuickBooks Bills only. Payroll, owner draws, and auto-debits not entered as bills are NOT included, so this is a bills-only check, not a full cash forecast. This tool does not pay anyone and changes nothing in QuickBooks - you pay through your bank or each vendor's portal.</small>

</Template - Bill Plan>