--- name: "Agreement Reconciliation" description: > Reconciling PSA contract/agreement entitlements (seats, hours, recurring services) against invoiced reality in an accounting platform, across any combination of PSA (Autotask, HaloPSA, ConnectWise, Syncro) and accounting platform (QuickBooks Online, Xero). Covers building the entitlement ledger, the cross-system matching priority, and the gap classes — under-billing, over-billing, lapsed agreements still invoiced, active agreements never billed, and price drift. when_to_use: >- When checking whether a client's PSA contract terms (seats, hours, recurring services) match what is actually being invoiced. Use when: billing drift, contract vs invoice mismatch, are we billing correctly, agreement reconciliation, under-billing, over-billing, lapsed agreement still invoiced, billing audit, contract compliance check. --- # Agreement Reconciliation ## Overview MSP revenue is only as reliable as the agreement it is billed against. A contract signed for 25 managed seats drifts silently when 5 new hires never get added to the invoice line, or when a client offboards a location and the recurring service never gets removed. This skill teaches Claude how to pull the **entitlement** (what the PSA contract/agreement says the client should be paying for) and the **invoiced reality** (what the accounting platform actually billed), and surface every place they disagree. The reconciliation answers one question: **"Does every active PSA agreement have a matching, correctly-quantified line item on the client's accounting invoices — and does every invoiced recurring line item still have a live agreement behind it?"** ### How this differs from `shared/skills/billing-reconciliation` The repo already ships [`shared/skills/billing-reconciliation`](../../../shared/skills/billing-reconciliation/SKILL.md), which is narrower and vendor-specific: it reconciles **Pax8 marketplace subscriptions** against **Xero/QuickBooks invoices** — a two-system, distribution-to-accounting comparison. This skill covers a different pair: **PSA contract/agreement entitlements** against **accounting invoices**, and it is written to be PSA-agnostic (Autotask, HaloPSA, ConnectWise, or Syncro — whichever is actually connected) rather than assuming a single accounting platform. The two skills are complementary, not competing, and a full month-end close often runs both: | | `shared/skills/billing-reconciliation` | `agreement-reconciliation` (this skill) | |---|---|---| | Entitlement source | Pax8 active subscriptions | PSA contract/agreement (seats, hours, recurring services) | | Comparison target | Xero / QuickBooks invoice lines | Xero / QuickBooks invoice lines | | PSA involved? | No | Yes — required | | Distributor involved? | Yes — required (Pax8) | No (see `license-true-up` for Pax8/Sherweb seat matching) | | Typical gap found | Unbilled marketplace seat | Under-billed contract, over-billed contract, lapsed agreement still invoiced | Reuse its matching strategy (fuzzy product/company name matching, amount tolerance bands, severity tiers) rather than re-deriving one — the logic transfers directly from "subscription line vs invoice line" to "contract term vs invoice line." ## Anti-triggers - **Working a contract record itself** — contract types, service and service- bundle associations, block hours, and renewals are the PSA's surface; use `autotask-contracts` or `halopsa-contracts`. - **Working an invoice itself** — creating, sending, or querying invoices is the accounting connector's surface; use `xero-invoices` or `quickbooks-online-invoices`. ## Connected Systems | System | Role | Required? | |--------|------|-----------| | PSA — Autotask / HaloPSA / ConnectWise / Syncro | Source of contract/agreement entitlements (seats, hours, recurring service lines, status, term dates) | Yes (at least one) | | Accounting — QuickBooks Online / Xero | Source of invoiced reality (line items, quantities, amounts, invoice status) | Yes (at least one) | ## Reconciliation Workflow ### Step 1: Discover what's actually connected Call `conduit__search_tools` first — do not assume Autotask, HaloPSA, ConnectWise, Syncro, QuickBooks Online, or Xero are connected just because they appear in examples below. Search for terms like `"contract"`, `"agreement"`, `"invoice"` to see which vendor-prefixed tools come back for this org, then proceed only with what's live. If exactly one PSA and one accounting platform are connected, the rest of this workflow is unambiguous. If multiple of either are connected (e.g. a client base split across two PSAs post-acquisition), run the reconciliation once per PSA and merge the reports. ### Step 2: Pull active PSA agreements/contracts For each connected PSA, pull active contracts/agreements per client. Resolve status and type IDs via each PSA's own list/lookup tools rather than hardcoding IDs — they are tenant-specific. - **Autotask** — `autotask__search_contracts` for active contracts, then `autotask__search_contract_services` (or the contract's service line detail) for the billed units per service (seats, block hours, recurring flat fee). - **HaloPSA** — `halopsa__clients_list` / `halopsa__clients_get` for the client's contract detail, or a dedicated contract-listing tool if the org exposes one. - **ConnectWise** — the agreement/contract search tool, expanded to include agreement additions (the line-item-equivalent of seats/services on a CW agreement). - **Syncro** — the customer's active contract/recurring-invoice-schedule detail. **Key fields to extract per agreement:** - Client/company identifier (to correlate against the accounting contact) - Service/product line description - Contracted quantity (seats, block hours, or "flat" for fixed-fee lines) - Unit price (billed rate — not the MSP's internal cost) - Billing frequency (monthly, quarterly, annual) - Contract status (active, expired, cancelled) and term end date **Build an entitlement ledger**, one row per contract line: ``` PSA Agreement Ledger ──────────────────────────────────────────────────────────── Client Contract Line Item Qty Unit Price Monthly Acme Corp Managed Services MSA Managed Seat 42 $145.00 $6,090.00 Acme Corp Managed Services MSA After-Hours SLA 1 $250.00 $250.00 Beta LLC Block Hours Q1 Prepaid Hours 20 $95.00 (prepaid, not recurring) Gamma Inc Legacy MSA (expired) Managed Seat 18 $120.00 $2,160.00 [EXPIRED 2026-04-30] ──────────────────────────────────────────────────────────── ``` Flag any contract whose term end date is in the past but status still shows active in the PSA — that is itself a data-hygiene finding worth reporting separately (the contract should have been renewed or closed). ### Step 3: Pull invoiced line items from accounting For the same billing period, pull sales invoices from whichever accounting platform(s) are connected. - **QuickBooks Online** — `qbo__list_invoices` (or the equivalent search tool), filtered to the billing period and, where possible, the specific customer. - **Xero** — `xero__list_invoices` for ACCREC (sales) invoices in the period, filtered by contact where possible. **Key fields:** customer/contact name, line description, quantity, unit price, line amount, invoice status (draft/authorised/paid), invoice date. ### Step 4: Match agreement lines to invoice lines Use the same matching priority as `shared/skills/billing-reconciliation`: 1. Client/company name match (PSA client to accounting contact/customer) — exact, then contains, then DBA/trading-name fallback, then ask the user. 2. Line-description fuzzy match (contract service name to invoice line description) — MSPs abbreviate ("Managed Seat" vs "MSP Managed Service — per user"). 3. Quantity comparison. 4. Amount comparison within a tolerance band (default ±5%; rounding and partial billing periods are common and not automatically a gap). ### Step 5: Classify gaps - **Under-billing (CRITICAL/HIGH)** — Contract quantity exceeds invoiced quantity (e.g. contract says 42 seats, invoice reflects 37). Dollar impact = `(contracted qty − invoiced qty) × unit price`. - **Over-billing (HIGH)** — Invoiced quantity exceeds contract quantity. This is a client-facing risk (overcharge, potential refund obligation), not just an MSP-favorable discrepancy — treat it with the same urgency as under-billing. - **Lapsed agreement still invoiced (CRITICAL)** — Contract status is expired/cancelled/terminated in the PSA, but a recurring invoice line for it is still appearing on current invoices. This is billing a client for a contract that no longer exists. - **Active agreement, no invoice found (CRITICAL)** — Contract is active in the PSA with no corresponding invoice line at all in the period. Distinct from a quantity mismatch — this is total non-billing. - **Price drift (MEDIUM)** — Quantities match but unit price on the invoice differs from the contracted rate (rate never updated after a contract amendment, or a manual invoice override). ### Step 6: Report Group findings by severity, always leading with dollar impact so the reader can triage by size, not just category. See Report Format below. ## Report Format ``` ═══════════════════════════════════════════════════════════════════ AGREEMENT RECONCILIATION REPORT Period: [Month Year] PSA: [Autotask / HaloPSA / ConnectWise / Syncro — whichever connected] Accounting: [QuickBooks Online / Xero — whichever connected] Generated: [Date] ═══════════════════════════════════════════════════════════════════ SUMMARY Clients Checked: [N] Contract Lines Reviewed: [N] Matched Clean: [N] Gaps Found: [N] CRITICAL: [N] (est. $[X]/month impact) HIGH: [N] (est. $[X]/month impact) MEDIUM: [N] ─────────────────────────────────────────────────────────────────── CRITICAL — Lapsed Agreements Still Invoiced ─────────────────────────────────────────────────────────────────── [Client] — [Contract name], expired [date], still billing $[X]/month Action: Confirm with account manager — either renew the agreement or remove the recurring line. ─────────────────────────────────────────────────────────────────── CRITICAL — Active Agreements With No Invoice ─────────────────────────────────────────────────────────────────── [Client] — [Contract line], [qty] contracted, $0 invoiced Action: Add missing invoice line; investigate why it was never billed. ─────────────────────────────────────────────────────────────────── HIGH — Under-Billing (Quantity Mismatch) ─────────────────────────────────────────────────────────────────── [Client] — [Line], contracted [X], invoiced [Y], $[Z]/month underbilled ─────────────────────────────────────────────────────────────────── HIGH — Over-Billing (Client Risk) ─────────────────────────────────────────────────────────────────── [Client] — [Line], contracted [X], invoiced [Y], $[Z]/month overbilled Action: Verify with account manager before next invoice — possible refund obligation. ─────────────────────────────────────────────────────────────────── MEDIUM — Price Drift ─────────────────────────────────────────────────────────────────── [Client] — [Line], contracted rate $[X], invoiced rate $[Y] ─────────────────────────────────────────────────────────────────── MATCHED — No Issues ─────────────────────────────────────────────────────────────────── [N] contract lines confirmed matching invoiced amounts within tolerance. ═══════════════════════════════════════════════════════════════════ ``` ## Graceful Degradation | Missing / Unavailable | Handling | |---|---| | No PSA connected | Cannot run — no entitlement source. State this explicitly; do not substitute invoice-only guessing. | | No accounting platform connected | Report the PSA agreement ledger as a standalone entitlement list; note reconciliation could not be performed. | | Multiple PSAs connected | Run the workflow once per PSA, merge into one report, and label each finding with its source PSA. | | Client exists in PSA but not in accounting | Flag as CRITICAL — likely an entirely unbilled client, same severity class as "active agreement, no invoice." | | Contract line has no clear per-unit price (fully bundled flat fee) | Compare total line amount instead of per-unit; note the comparison basis in the report. | | PSA contract data incomplete (e.g. missing term end date) | Note as a data-hygiene flag alongside billing findings — don't silently skip the line. | ## Related Skills - [`shared/skills/billing-reconciliation`](../../../shared/skills/billing-reconciliation/SKILL.md) — Pax8 subscription vs. accounting invoice reconciliation (distribution layer, not PSA) - [`license-true-up`](../license-true-up/SKILL.md) — Pax8/Sherweb subscription seats vs. billed vs. actually deployed seats - [`margin-analysis`](../margin-analysis/SKILL.md) — turns reconciled revenue into per-client margin once billing is confirmed accurate