---
name: month-end-close
description: "Run the monthly close, reconcile completions against fees received, compute the commission run, surface variances, and produce the pack for the accountant. Triggers when the operator says 'close out <month>', 'close <month>', 'month end', 'do my commission', 'commission run', 'reconcile <month>', 'ready for the accountant', 'what did I do last month'. Also fires automatically on the first working day of the month."
---

# Month-end close

The master workflow owned by the compliance specialist. Compresses a half-day to a full day of month-end admin into a 20-minute review. Produces a clean pack ready for the accountant.

This is the workflow that earns back the subscription. A solo agent who would otherwise spend half a Saturday on this should feel that Real Agent paid for itself in the time saved on month-end alone.

## Inputs

- The period to close (typically the previous calendar month).
- The customisation profile.

The workflow reads the rest from connectors.

## Architecture principles encoded here

- Read before write. The workflow opens by reading completions, fees received, the commission splits table, and the prior close pack. It writes nothing until the operator approves each individual stage.
- Stage, don't send. Journal entries, payment batches, accountant emails are all staged. Approval is per item.
- One screen of output. The pack is five sections, each summarised on one screen. Drill-down is available on request.
- Cite the source. Every line in the reconciliation cites the completion record and the bank transaction it matched against. Every commission line cites the splits table and the deal.
- Teach the profile. Categorisation conventions, variance tolerance, narrative tone all feed back through `profile-writer`.
- Reversible. No transfers are initiated. Journal postings require explicit approval. The accountant pack is drafted and queued; nothing sends without the operator.

## Output shape

Five sections, in this order.

1. **Completions.** Every property that exchanged or completed in the period: address, vendor, buyer, fee value, fee structure (sole, multi, withdrawal, sliding), completion date, expected receipt date. Anything that exchanged but is still awaiting completion is highlighted.
2. **Reconciliation.** Fees expected versus fees received, matched on completion date and amount. Three flag categories: matched, pending (expected but not yet received with age), variance (received differs from expected: fee adjustment, referral deduction, fee dispute). Variances get a one-line cause and a draft email to the accountant or the solicitor if appropriate. Built by `period-reconciler`.
3. **Commission run.** For office tiers with multiple agents: each agent's earned commission for the period, referral fees passed through, franchise levies deducted, pre-agreed adjustments. Built by `commission-calculator`. Presented as a payable schedule with totals.
4. **Pipeline carry-forward.** Sale-agreed but not yet exchanged, with expected exchange or completion month, fee value, current fall-through risk pulled from `chase-progression`. One-line narrative of next month's expectation.
5. **Variance narrative.** Two paragraphs comparing the period to the previous month and to the same period last year, in plain language. Built by `variance-narrator`. Suitable to paste into a board update, a tax-return cover note, or a conversation with a partner.

## Approval gates

- **Variance writeoffs.** Any fee variance the workflow proposes to write off (FX, small reconciliation differences) requires per-item approval.
- **Commission payment batch.** Staged by `payment-batch-stager`. No transfer is initiated; the operator approves the batch for export to their bank, or makes payments manually using the schedule.
- **Journal entries.** Any postings to the accounting system require approval. The default behaviour is to propose postings, show what they would do, and let the operator approve before they hit the books.
- **Accountant pack send.** The drafted email to the accountant with the pack attached requires explicit approval before send.

## Continuous learning hooks

- Categorisation conventions. The accountant prefers a specific chart-of-accounts mapping. Corrected once, learned for every subsequent close.
- Variance tolerance. Default writeoff threshold tightens or loosens based on overrides.
- Narrative tone. Voice for the variance paragraphs learned from edit-before-approve diffs.
- What to flag. "I always want to know about completions over GBP 5,000 fee value" leads the pack with those. "Don't bother flagging multi-agency fee splits separately" suppresses that detail.
- Pipeline narrative confidence. Over time the workflow learns how accurate its "next month should look like X" predictions are and adjusts the confidence language.

All writes go through `profile-writer`.

## Connectors

Read: accounting (Xero, FreeAgent, QuickBooks, Sage), bank feed via the accounting connector, CRM, prior month's close pack.
Write: accounting (journal entries on approval), payment batch staging for the bank or for a payroll-style export, Drive (close pack storage), email (accountant pack).

## Profile keys

- `realagent.accounting.platform` ("xero" | "freeagent" | "quickbooks" | "sage")
- `realagent.accounting.chart_of_accounts_map` (learned)
- `realagent.close.writeoff_threshold_gbp` (default 5)
- `realagent.close.flag_threshold_fee_gbp` (default 5000)
- `realagent.close.narrative_voice_samples` (learned)
- `realagent.close.pack_recipients` (accountant email addresses)
- `realagent.commission.splits_table_path`
- `realagent.commission.franchise_levy_pct`