agentleFS
samsational-codesamsational-code/business-skills/payout-reconciliation-checker/SKILL.md

payout-reconciliation-checker

Skill0 starsChanged 2 months agoMITView on GitHub

Independently recompute any formula-driven payout from the raw activity data and the governing agreement's own words, then reconcile the result against the counterparty's, administrator's, or internal model's statement line by line — thresholds and tiers, accelerators and hurdles, catch-ups, caps, splits, and the current clawback or true-up position. Covers sales commissions, revenue share, profit share, royalties, bonus pools, earn-outs, referral and affiliate payouts, franchise fees, and fund distribution waterfalls. For finance teams, controllers, sales operations, licensing and royalty managers, partnership managers, M&A integration teams, fund accountants, and anyone who has to approve a payout or dispute one. Trigger on phrases like "check this commission statement," "recompute the royalty," "does the partner's revenue-share calculation tie," "verify the bonus pool," "what's our clawback exposure," "model the earn-out from the agreement," "review this payout before it goes out," "we're $X apart and nobody can find it," or when a user uploads activity data, a compensation or licensing agreement, or a payout statement. Do NOT use for drafting the payee-facing statement or communication — use the stakeholder-update-generator skill. Do NOT use for extracting bespoke economics from a side letter — use the side-letter-term-extractor skill. This is an independent check, not the official calculation, and not tax, accounting, or legal advice.

The file

We split this skill into the rules it gives an agent

1 rule. About 0 are common, 1 is distinctive, and 0 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈1

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 0

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    Never fabricate a transaction: If the history has gaps, the recomputation stops there.

    line 152

≈ “Common” is an estimate: at least 1 in 5 of the 350,495 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

Payout Reconciliation Checker

Recompute the payout from the raw activity data and the agreement's own words, then compare against the calculation you were handed — and when the two disagree, trace exactly where they diverge: which payee, which tier, which assumption, and how many dollars. The point is two genuinely independent calculations that agree, rather than one calculation reviewed twice.

Why this skill exists

A formula-driven payout is the highest-stakes arithmetic in most organizations. It determines what every salesperson, partner, licensor, seller, or investor receives and what the organization keeps; it is governed by a document written by lawyers or HR rather than by modelers; and it typically lives in a single spreadsheet maintained by one person — checked against a counterparty, administrator, or commission system running their own version of the same spreadsheet, built from the same summary of terms. Two models built from the same abstract are not independent. When they disagree, the reconciliation is a week of archaeology conducted after someone has already asked when the payment is going out. This rebuilds the calculation from the primary sources and localizes any difference to a line, before the payment, not after.

Inputs

Required:

  • The complete activity history the payout is computed on, by date and by payee (or at minimum by group, if payee-level detail is unavailable): bookings, invoices, collections, units sold, streams or downloads, net sales, net profit, EBITDA, capital calls and distributions — whatever the agreement measures
  • The governing agreement's payout provisions, plus the relevant defined terms — verbatim, not a summary: the commission plan, revenue-share or licensing agreement, bonus plan document, purchase agreement earn-out schedule, franchise agreement, or partnership agreement distribution section
  • The calculation being checked: the counterparty's statement, the administrator's schedule, the commission system's output, or the internal model's result, for the payout in question

Optional but high-value:

  • Side letters, addenda, or individual exceptions affecting economics — negotiated rates, guaranteed minimums, special territories, most-favored-nation elections, custom splits
  • The payee register with plan assignments, start and end dates, territories, quotas, or commitment amounts (essential if payees joined, left, or changed plans mid-period)
  • Prior period statements, so running balances — cumulative attainment, carried-forward shortfalls, accrued preferred returns, prior clawbacks — can be verified rather than assumed
  • Current pipeline, open receivables, return and refund history, or portfolio carrying values, for the clawback and true-up assessment
  • Anything that changes timing: when revenue is recognized vs. billed vs. collected, when a deal counts as closed, when a distribution is deemed made

Missing-input behavior: All three required inputs are genuinely required — a payout cannot be recomputed from a summary of terms, and comparing against nothing is not a check. Ask once, specifically, for whichever is missing. If payee-level data is unavailable but aggregate data is, run the check at the aggregate level and label the output clearly as an aggregate check that cannot detect payee-level allocation errors. If the agreement text is paraphrased rather than quoted, say that the check is only as good as the paraphrase and ask for the actual sections.

How it works

  1. Restate the payout in mechanical terms before computing anything. Read the agreement provisions and write out the structure as an explicit sequence of steps: what is measured (of what — gross or net, booked or collected, before or after returns and discounts?), the threshold or hurdle that must be cleared, the rate or split at each tier, any accelerator or catch-up, any cap, and the residual. Get the user's confirmation on any ambiguity before running numbers. Most payout disputes are definitional, not arithmetic.
  2. Fix the convention questions explicitly. Measurement period and cutoff, what counts toward the base (which products, territories, customers, deal types), timing (booked vs. invoiced vs. collected), how returns, refunds, credits, discounts, and chargebacks are treated, attribution and split rules when more than one payee touches a transaction, currency and exchange-rate dates, rounding, whether accrual is simple or compounded, day count, and treatment of carried-forward balances. List each convention and cite the agreement section that establishes it. Where the agreement is silent, say so and state the convention you applied.
  3. Build the base schedule from the activity history, by payee, period by period, from the start of the plan or fund to the payout date. Show the running balance — cumulative attainment, cumulative net sales, unreturned capital, accrued preferred return, whatever the structure tracks.
  4. Run the base through the tiers, allocating step by step and showing the amount at each tier and the balance remaining after it.
  5. Compute the accelerators, catch-ups, caps, and splits, noting the exact base each is measured against and whether it is full or partial.
  6. Reconcile line by line against the provided calculation. For every line that differs, isolate the cause: a different base definition, a different treatment of a specific transaction, a payee who joined or changed plans mid-period, a side letter or exception, a date or cutoff difference, a currency difference, or an arithmetic error. Quantify the dollar impact of each cause.
  7. Compute the clawback or true-up position — what has been paid to date versus what would be due if the period were closed, all open items resolved, and all provisional amounts finalized today (cancelled deals reversed, refunds netted, earn-out targets measured, the portfolio liquidated at carrying value), net of any holdbacks, escrows, reserves, or advances the agreement provides. Flag if the position is negative for the organization.
  8. Write the memo for the payout approval file.

Output format

# [Plan / Agreement / Fund] — Payout Check, [Period] Payout of $[amount]
Payout type: [commission / revenue share / royalty / bonus pool / earn-out / distribution waterfall / other]
Sources: [activity data file] | [agreement §§] | [calculation being checked, version/date]
Level of check: [payee-level / aggregate] | Structure: [tiered / flat / whole-period / per-transaction]

## Bottom line
Agree / Disagree. If disagree: the number of differences, the largest one in
dollars, and whether it changes any payee's amount or the organization's
retained share.

## Payout structure as restated from the agreement
Step 1: [description] [§]
Step 2: [description] [§]
Step 3: [description] [§]
Step 4: [description] [§]

## Conventions applied
| Convention | Applied | Agreement basis | Note |
|---|---|---|---|
| Base definition | | [§] | |
| Measurement period / cutoff | | [§] | |
| Timing (booked / invoiced / collected) | | [§] | |
| Returns, refunds, credits | | [§] | |
| Attribution / split rule | | [§] | |
| Rate, tier thresholds, accelerator | | [§] | |
| Cap / floor / guaranteed minimum | | [§] | |
| Carry-forward treatment | | [§] | |
| Currency / rounding / day count | | [§] | |
[Mark any convention where the agreement is silent or ambiguous.]

## Independent recomputation
### Base schedule
| Payee | Gross activity | Exclusions / netting | Qualifying base | Cumulative | Running balance |
|---|---|---|---|---|---|

### Tier allocation of this payout
| Tier | Threshold | Rate / split | Amount allocated | Cumulative | Remaining |
|---|---|---|---|---|---|

### Accelerators, catch-ups, caps
[Amount] | Base measured against: [ ] | Cumulative to date: $[ ]

## Reconciliation to [counterparty / administrator / system / internal model]
| Line | Our figure | Their figure | Difference | Cause |
|---|---|---|---|---|
[One row per differing line. Cause must be specific — a mechanism, not "rounding"
unless the difference is genuinely sub-dollar.]

Total difference: $[ ] | Payees affected: [list or count]

## Clawback / true-up position (as of [date])
Paid to date: $[ ]
Due on final measurement / hypothetical close-out: $[ ]
Exposure: $[ ] | Holdback / escrow / reserve held: $[ ] | Net: $[ ]
Sensitivity: exposure at [-10%] / [-25%] on the open or provisional items: $[ ] / $[ ]

## Items requiring a human decision
Numbered. Ambiguous agreement language, side letter interactions, or
conventions the document does not settle.

Where payouts actually break

The differences are almost never arithmetic. In order of how often they cause a reconciliation break:

  • Base definition — gross vs. net; booked vs. invoiced vs. collected; with or without discounts, credits, taxes, shipping, returns, and refunds; unreturned capital only vs. all contributions including fees. Two reasonable readings diverge substantially over a plan's or fund's life.
  • Period and cutoff — a deal closed on the last day of the month, a payment received two days after quarter end, an accrual that runs to the payout date vs. the period end. Which period a transaction lands in changes the tier it hits.
  • Tier mechanics — whether a higher rate applies retroactively to the whole base or only to the increment above the threshold; whether tiers reset each period or run cumulatively; whether an accelerator applies to the whole amount or to overage.
  • Compounding and accrual convention — simple vs. compounded, annual vs. quarterly, from transaction date or period end. An 8% preferred return compounded quarterly is not an 8% preferred return; a "monthly" quota measured on a rolling basis is not a calendar-month quota.
  • Mid-period changes — payees who started, left, changed plan, changed territory, or were admitted at a later closing; pro-ration rules and whether a departed payee earns on deals that close after departure.
  • Attribution and splits — overlays, team credit, house accounts, referral chains, co-sell, and multi-territory deals where more than one payee claims the same transaction.
  • Catch-up base — whether a catch-up or true-up is measured against the preferred amount only, or against the preferred amount and the returned base. The second is far more favorable to the recipient and both appear in market documents.
  • Recycled, recalled, or reversed amounts — recallable distributions, cancelled orders, chargebacks, and returned goods that reduce the base, may increase it again later, and may or may not restart accrual.
  • Timing effects from financing — capital called late because a credit line funded the investment, or revenue recognized before cash arrives. Accrual usually runs from the actual date, so the financing choice moves the clock; confirm whether the agreement has a deemed-date provision.
  • Loss and shortfall carryforwards — whether prior losses, write-downs, missed minimums, or negative balances must be recovered before the next payout is earned.
  • Side letters and exceptions — reduced or enhanced rates, guaranteed minimums, fee offsets, or bespoke terms for specific payees that the standard model does not carry.
  • Advances and draws — treated as advances against future earnings or as a separate tier, and whether they count toward the clawback calculation.
  • Excluded parties and transactions — payees excused from specific deals, house accounts, intercompany sales, or defaulting participants that break the assumption that everyone shares pro rata.
  • Offsets and credits — transaction fees, monitoring fees, platform fees, or marketing contributions that reduce one line, change the base, and therefore change everything downstream.

Guardrails

  • Recompute from primary sources. The check is only independent if it is built from the raw activity data and the agreement's own language, never from the counterparty's summary of terms or a prior model's assumptions. If you find yourself adopting an input from the calculation being checked, say so explicitly — that line is no longer independently verified.
  • Every convention cites an agreement section. Where the agreement is silent or ambiguous, do not pick a convention silently: state the ambiguity, state which reading you applied, and quantify what the other reading would produce.
  • Never fabricate a transaction. If the history has gaps, the recomputation stops there. A payout built on inferred activity is worse than no check.
  • Differences get a mechanism, not a shrug. "Rounding" is only acceptable for genuinely sub-dollar differences. Every material difference is traced to a specific cause or explicitly labeled unexplained.
  • This is a check, not the official calculation. The agreement governs, the system of record or administrator's books are the record, and this output is a review workpaper — not a payment instruction, not an accounting opinion, and not a basis for a wire or a payroll run.
  • Not tax, accounting, or legal advice. Clawback, advance, earn-out measurement, and allocation questions have tax, accounting, employment-law, and contractual consequences that belong with counsel and the organization's advisors.
  • Confidentiality: payee-level compensation and cash flow data is highly sensitive. Assume an organization-approved AI environment; do not reproduce individual names or amounts beyond what the check requires.

Quality checks

  • Payout structure restated as explicit steps before any computation
  • Every convention has an agreement citation, or is flagged as not established by the document
  • Base schedule shown period by period with running balances, not just a total
  • Reconciliation covers every differing line, each with a specific mechanism
  • Dollar impact quantified per difference and in total
  • Payee-level vs. aggregate scope stated at the top
  • Clawback / true-up position computed with a sensitivity, not a single point
  • Ambiguities surfaced as decisions for a human rather than resolved silently
  • No input silently adopted from the calculation being checked

Example prompts

"Attached: Q3 closed-won bookings by rep from the CRM, the FY commission plan document, and the commission system's statement for the payout going out on the 15th. Recompute it independently and tell me whether it ties. Tiered plan, accelerator above 100% of quota, quarterly reset."

"Our licensor says we underpaid royalties by $180k over the last four quarters. Here's the license agreement, our net sales by SKU and territory, and their audit schedule. Where do we actually diverge, and what's the number if their reading of 'Net Sales' is right?"

"We share 30% of net revenue with our channel partner. Their statement and ours are $47k apart for the half-year and nobody can find it. Both schedules, the transaction export, and the partner agreement are attached."

"Year-two earn-out measurement on the acquisition. Purchase agreement earn-out schedule pasted below, the business unit's P&L attached. Compute what's due, reconcile to the sellers' claim, and show me the sensitivity if the working-capital adjustment goes their way."

"Fund distribution waterfall check. Full call and distribution history by investor, the partnership agreement's distribution sections, and the administrator's schedule for the $42M distribution are attached. Recompute it, tell me whether it ties, and give me the clawback position at current carrying values."

Works well with

Use side-letter-term-extractor first if specific payees have bespoke economics that need to be reflected in the calculation, and contract-obligations-extractor to pull the full set of defined terms and adjustments from a long-form agreement before restating the structure. Pair with stakeholder-update-generator once the payout is approved and the payee-facing communication is being written.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.