business-pulse

Overview

Produces a 60-second-readable business health briefing from QuickBooks data, with optional calendar, email, and Slack context.

Workflow

<Definition - Aging Buckets> Accounts receivable grouped by how far each invoice is past ITS OWN due date, measured from the invoice's DueDate, which already reflects its terms (net-15/30/60/90 or custom). Buckets: Current (not yet past due), 1-30 days past due, 31-60, and 61+. Never measure aging from the invoice date and never assume net-30. "Newly overdue" means an invoice that passed its own DueDate since the previous briefing. Old is not the same as overdue: construction retainage and insurance-claim balances can sit for a long time by arrangement without being late. Do not treat a heavy 61+ bucket as a problem unless those balances are genuinely past their due dates. </Definition - Aging Buckets>

<Definition - Cash Coverage Ratio> Total spendable cash (Bank accounts only, excluding restricted funds and excluding Other Current Asset per step 3) divided by total accounts payable due in the next 7 days. Above 1.5 is comfortable, 1.0 to 1.5 is tight, below 1.0 is short. This ratio drives the tone and recommendations in the narrative. </Definition - Cash Coverage Ratio>

<Definition - Anomaly> What counts as an anomaly depends on the business, and on a single briefing the skill has no baseline for what is normal for THIS business. So separate two tiers, and never present a Tier B item as an error.

Tier A, confident problems (flag for any business, no baseline needed):

• Overdrawn or negative operating cash balance.
• A failed, bounced, returned, or declined payment.
• Cannot cover must-pay obligations due this week (payroll, rent, loan, tax) from available cash, a coverage breach. Scope this to must-pay items, not every vendor bill.
• A record that looks wrong and is worth confirming: missing a required field (invoice with no customer, bill with no vendor), an apparent duplicate (same customer, amount, date, and number), or a figure that looks mis-keyed (an obvious extra zero, or a value well out of line with every peer in its set). Flag it and ask. Never exclude it from a total and never call it fake; the ledger figure stands until the owner corrects it in QuickBooks (Rule 11).
• An invoice that passed ITS OWN due date since the last briefing, terms-aware, using each invoice's DueDate (which already encodes net-15/30/60/90 or custom terms). Never assume net-30. If an invoice has no terms or DueDate on file, do not assume it is overdue; treat it as a Tier B item to confirm (and a candidate for a single targeted question per <Definition - Anomaly Handling>).

Tier B, observations worth a look (surface gently, Info, framed "confirm if expected", NEVER labeled an error, and stop surfacing once the owner says it is normal):

• A single large invoice or client (could be the biggest job or the anchor client, not an error).
• Customer or vendor concentration above {{concentration_threshold}} of a total (could be the business model: one GC, one anchor client, one insurer).
• An expense well above its category's recent average (could be materials, a restock, payroll, or a quarterly/annual bill).
• Large or aging receivables (could be construction retainage, insurance-claim lag, or favorable preferred-partner terms; old is not overdue).
• A negative or credit AR balance (usually a customer deposit, retainer, or prepayment, not money owed).

Business shape matters, so do NOT assume an AR-centric, net-30 business:

• Many businesses (retail, restaurants, COD trades) carry little or no AR. Empty receivables is normal for them, not a sync problem. Only zero ACCOUNTS returned (no bank data at all) is a likely sync issue.
• Project and trade businesses have lumpy cash and lumpy expenses by nature (a deposit lands, then a big material buy); that swing is normal, not an anomaly.
• Some "cash" is not the owner's to spend: accounts whose name suggests trust, IOLTA, escrow, holding, or reserve hold restricted funds. Do not fold these into spendable cash silently; separate or flag them. </Definition - Anomaly>

<Definition - Order-of-Magnitude Outlier> Within a set of comparable figures (open invoices, customer balances, bills due, expenses in a category), any value at least 10x larger than the median of the OTHER values, or at least 10x the next-largest value. Baseline against the other items, never the full set, so an outlier cannot inflate its own benchmark. Require a meaningful set first: with fewer than 4 items, skip this check (10x is trivial in a tiny set). Flag EVERY record that meets the test, not just the biggest. When several large records are present (including large credits or negatives), they can mask each other, so judge each record against the median of all the others and surface every one that qualifies. An outlier is, by itself, only a Tier B observation. Surface it as "unusually large, confirm if expected", because it is often a legitimate big job, a major one-time purchase, or an anchor client. Never exclude it from a total and never declare it fake (Rule 11). When a record ALSO looks mis-keyed (an obvious extra zero, or a figure wildly out of line with its peers) or dominates a headline total, raise its urgency, flag it prominently and ask the owner to confirm, but still report the real total that includes it. Example: a plumber's open invoices of ~$450 each plus one of $4,500. Report the real total including the $4,500 and flag it as "unusually large, please confirm" (it may be a real job, or a $450 typed with an extra zero); any hypothetical is computed exactly per <Definition - Anomaly Handling>, never eyeballed. A single real $6,800 install among $450 service calls is just a Tier B "confirm". </Definition - Order-of-Magnitude Outlier>

<Definition - Anomaly Handling> One consistent rule for every anomaly. For each one: name the specific record (customer or vendor, amount, date), assign a severity, and give a one-line plain-language reason. Never drop, exclude, or net out a record to "clean up" a total. The ledger is the authority (Rule 11); always report the real total including every record. When one or more flagged records dominate a headline total (total cash, total money owed to you, or total bills due), you MAY add a single clearly-labeled hypothetical beside the real figure. Compute it exactly: take the real total and remove the flagged records' own amounts (subtract a positive, add back a credit or negative) so it reconciles to the cent. State it once and only once: never give two different reduced numbers, and never estimate, round, or eyeball it. Account for every record you flagged, not just one. If you cannot compute it exactly, omit it. Always lead with the real total; the hypothetical is secondary and optional. Example: "You're owed $X in total (the real figure). If the records I flagged are mistakes, the total would be exactly $Y, can you confirm them?"

Severity and framing follow the tiers in <Definition - Anomaly>:

• Critical (Tier A): overdrawn cash, a failed/bounced payment, a coverage breach on must-pay obligations, or a mis-keyed figure that distorts a headline number.
• High (Tier A): a record that looks wrong and needs confirming (missing required field, apparent duplicate), or an invoice newly past its own due date for a material amount, flagged for the owner, never excluded.
• Info (Tier B): everything business-shaped: large client/outlier, concentration, big-vs-category expense, large/aging AR, credit balances. Frame these as "worth confirming if this is expected", never as an error, and stop surfacing an item once the owner confirms it is normal (remember the decision).

When in doubt about whether something is a problem or just this business's normal, treat it as Tier B and say plainly that you do not yet know the business's baseline.

Ask, don't assume, but only on a surfaced anomaly. When a flagged item hinges on context that is not in QuickBooks or memory (for example, an invoice with no terms on file, or whether a single large client is expected), ask one targeted, plain question (e.g. "This invoice to Mr. Jones has no payment terms on file. When do you expect to be paid: 30 days, 60 days, or something else?") and store the answer for next time. Always read the terms and DueDate QuickBooks already holds and check memory first; never ask about anything already known or derivable. Outside of a surfaced anomaly, stay silent: observe and learn, do not quiz the owner. </Definition - Anomaly Handling>

<Definition - Revenue-Generating Event> A calendar event whose title contains client-facing keywords (client, customer, appointment, job, service, delivery, install, consultation). These are distinguished from internal events (standup, team, 1:1, planning, sync) and personal events (lunch, break, doctor). </Definition - Revenue-Generating Event>

<Workflow - Business Pulse description="Pull financial data, detect anomalies, and deliver a plain-language briefing." tools=[quickbooks, google-calendar, outlook, gmail, slack, agent_management, memory_management] triggers=["how's my business doing", "business pulse", "what's my cash position", "who owes me money", "what do I owe this week", "give me my morning briefing", "daily summary", "where do we stand financially"]

1. [Agent] Confirm QuickBooks is connected and note which optional connectors (google-calendar, outlook, gmail, 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 generate your Business Pulse. 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 from the timestamp.

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

3. [Agent] Query QuickBooks for cash position. Spendable cash is Bank-type accounts only: query active accounts of type Bank and sum CurrentBalance for total spendable cash, capturing each account name and balance. Exclude from spendable cash any Bank account whose name suggests restricted funds (trust, IOLTA, escrow, holding, reserve). List those separately. Do NOT fold Other Current Asset accounts into spendable cash: Other Current Asset can include undeposited funds, prepaids, and inventory, which are not spendable bank cash. If Other Current Asset accounts exist, you may show their total as a separate, clearly labeled line ("Other current assets, not counted as spendable cash"), never inside the headline Cash figure. Validate: At least one Bank account is returned and the spendable-cash sum is a number; restricted and Other Current Asset balances, if any, are shown separately and not included in the spendable total. If fails: Retry once. If still failing, note "couldn't load your cash balances" in the briefing and continue.

4. [Agent] Pull what you are owed. The headline "still unpaid" total must equal QuickBooks' own accounts-receivable total, which already nets credit memos and unapplied customer credits against open invoices. CRITICAL: a query for open invoices with Balance > '0' returns ONLY positive invoices and silently omits credit memos and unapplied customer credits, which are a SEPARATE record type with a negative balance. Relying on that query alone overstates what you are owed and produces a false "no credits" result. So retrieve BOTH: (a) open invoices (Balance > '0') for the aging breakdown, and (b) credit memos and unapplied customer credits. If the connector cannot return credit memos directly, take the headline net from customer balance detail (which already nets them) so the total still matches QuickBooks. Never report a "no credits" total that is really just the gross of positive invoices. Group the positive invoices into the four buckets per <Definition - Aging Buckets> (measured from each invoice's own DueDate, never a fixed 30/60/90), label that breakdown "How overdue" and never "Aging" (Rule 12). Show the credit memos and negative balances on a separate "Credits and deposits" line. The positive buckets plus the (negative) credits line equal the net headline total (worked example: $20B of invoices offset by a $12.3B credit memo is $7.7B net owed, never $20B). Sort by amount descending and flag any invoice newly past its own due date. Run the outlier check (per <Definition - Order-of-Magnitude Outlier>) over the WHOLE set INCLUDING credit memos, and flag EVERY record that qualifies: a giant credit memo is surfaced and confirmed exactly like a giant invoice, never dropped. Never exclude, hide, or net away any record (invoice or credit) from the total or the briefing (Rule 11). If any records are flagged, you MAY add a single, exactly-computed hypothetical (net total minus ALL flagged records, adding back any flagged credit per <Definition - Anomaly Handling>) stated once, as a question, never a correction. Validate: credit memos were actually queried (a "no credits" result is valid ONLY if a credit-memo / customer-credit query truly returned none, never because only Balance > '0' invoices were pulled); the headline equals QuickBooks' AR total (invoices net of credit memos), not the gross of positive invoices; the positive buckets plus the credits line equal that net; every qualifying outlier including credit memos is surfaced; any hypothetical equals the net total minus all flagged records. If fails: Retry once. If still failing, note "couldn't load what you're owed" and continue.

5. [Agent] Query QuickBooks Bills with Balance > '0' and DueDate within the next 7 days. Sum balances for total AP due this week and list each bill with vendor, amount, and due date. Validate: Query returns a list (empty is valid) and the sum is a number. If fails: Retry once. If still failing, note "couldn't load your bills" and continue.