/agreement-reconciliation

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 `qbo-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 ent