Skip to content

Plan: management reporting (profit and loss, key figures, cash forecast) ​

Status: plan, awaiting the Product Owner's approval; no code yet.

Why ​

An accountant who is paying attention tells the owner, every month: how the company did, where the money is, what is owed each way, what tax is coming, and whether cash will run short. FEAW's owner gets this once a year, with the accounts. GetMy Books already reads the pieces (bank lines, open invoices and bills, the VAT draft, the deadline radar). This plan puts them together into five read-only reports, delivered through Claude like every other tool.

It serves the vision ("watches the books ... surfaces savings") and SM-2 (cash collected sooner, a dividend taken safely). There is no capability for it yet: it needs a new one (see Decisions). It is not a dashboard of our own (docs/not-doing.md): every report is an MCP tool reply read in Claude.

House rules that shape every section:

  • Money is integer pence, and every figure comes from pure code in src/rules/ (new files profit-and-loss.ts, key-figures.ts, cash-forecast.ts, recurring.ts, month-end.ts). No I/O there; "today" is passed in as a London date.
  • Code builds the words too. Each tool returns a code-built summary first (headline, tables in pounds, dates as 30 Sep 2026), then the full data as structuredContent, through the src/present/ layer from issue #96 (UI 1) and #97 (UI 2). Claude quotes it; it never adds, divides or rounds.
  • Entity from the session only, under RLS. Nothing here writes to Xero. The only thing stored is the owner's settings (cash buffer, recurring list).

1. Monthly profit and loss ​

What the owner sees ​

text
FEAW SERVICES LTD: profit and loss, September 2026 (accruals, from Xero)
Net profit £6,450.00, up £2,570.00 on August and £550.00 on September 2025.

                     Sep 2026    Aug 2026    Sep 2025   Year to date
                                                        (Apr-Sep 2026)
Sales              £18,400.00  £15,250.00  £16,900.00   £97,300.00
Cost of sales       £2,100.00   £1,950.00   £2,300.00   £12,400.00
Gross profit       £16,300.00  £13,300.00  £14,600.00   £84,900.00
Overheads           £9,850.00   £9,420.00   £8,700.00   £57,600.00
Net profit          £6,450.00   £3,880.00   £5,900.00   £27,300.00

Largest changes on August: Sales +£3,150.00; Software +£380.00.
Accounting period 1 Apr 2026 to 31 Mar 2027: 6 of 12 months.
Warning: 4 Starling lines in September are not reconciled in Xero, so these
figures may be incomplete (see bank_reconciliation_check).

(All figures synthetic.)

Data sources and Xero endpoints ​

  • GET /api.xro/2.0/Reports/ProfitAndLoss with fromDate and toDate. The endpoint also takes periods (1 to 12), timeframe (MONTH, QUARTER, YEAR), trackingCategoryID, standardLayout and paymentsOnly (cash basis). Response: ReportWithRows (sections, rows, cells; account cells carry the account ID as an attribute).
  • GET /Organisation (accounting.settings.read, held): financial year end day and month, so year to date runs from the start of the accounting period.
  • Scope: accounting.reports.profitandloss.read (new). Xero's generic OpenAPI file still lists the broad accounting.reports.read, which is not available to apps created from 2 March 2026. This repo already requests the granular accounting.reports.banksummary.read (src/xero/session.ts). One Xero reconnect per entity; do it in the same reconnect as SPEC-005 and SPEC-006 if the timing allows.

Reports API or journals: use the Reports API.

Xero's ProfitAndLoss reportBuilt from journals
Matches what the accountant and Xero showYes, by definitionOnly if our code copies Xero's layout and rules
AccessGranular report scope, any tierGET /Journals needs accounting.journals.read, the Advanced tier and a security assessment (ADR 0024)
CallsOne per columnPaged through every journal
DetailAccount totals onlyLine level

Journals are ruled out by the tier alone. When the owner asks "why did Software go up?", the tool drills into invoices, bills and bank transactions for that account and month (scopes already held), not into journals.

Method ​

  • One call per column with explicit fromDate and toDate: this month, previous month, same month last year, year to date (4 calls). Not periods and timeframe: Xero's comparison columns are reported to drop the 31st of the month from earlier periods when the base month has 30 days (Xero developer community; CData's documentation).
  • Parse rows into { accountId, name, section, pence } in src/xero/, then pure code builds the table, the differences and the "largest changes" (top 3 by absolute change, from code).
  • Self-check: in code, the section rows must add up to Xero's own section totals and to Net Profit. If not, the tool refuses with a plain reason rather than showing a figure that does not tie.
  • Accruals basis by default (what the accounts use); cash basis (paymentsOnly=true) on request (see Decisions).
  • Warn when SPEC-003 finds unreconciled lines in the month.

Limits ​

  • Xero's figures are only as good as the books: unreconciled lines, uncoded receipts and missing bills make the month wrong. The warning says so.
  • Year-to-date and same-month-last-year ranges: Xero's docs are reported to require fromDate within a year of toDate. Both ranges fit; to confirm there is no "within a year of today" limit for last year's month.
  • No budgets or targets in this slice.

2. Balance sheet snapshot and key figures ​

What the owner sees ​

text
FEAW SERVICES LTD: key figures at 30 Sep 2026
Cash after what is owed (before customers pay): £1,282.95

Cash at bank        Starling £24,310.55 (bank balance; Xero shows £23,980.10,
                    difference is 4 unreconciled lines)
Amex card           £1,842.20 owed, due 9 Oct 2026
Owed to us          £21,640.00 from 7 customers, £5,200.00 overdue
Owed by us          £3,915.40 on 5 bills, none overdue
VAT                 £5,400.00 for Jun-Aug, due 7 Oct 2026
                    £3,120.00 so far for Sep-Nov (cash accounting)
PAYE and NI         £1,850.00, due 22 Oct 2026
Corporation Tax     £6,900.00 to set aside (estimate, see owner-director-money)

Balance sheet (Xero): net assets £48,700.00; retained profits £41,200.00.

"Cash after what is owed" is Starling, less the card, bills, VAT, PAYE and Corporation Tax. Debtors are shown but not counted.

Data sources and Xero endpoints ​

FigureSourceScope
CashStarling balance (existing read-only token); Xero Reports/BankSummary closing balance per accountheld
AmexLatest statement file balance and due date (statements/, SPEC-003)none
Owed to us, by uspayments_aged (SPEC-006, src/rules/aged-balances.ts)held
VATSPEC-001 derivation (src/vat/derive-return.ts, cash scheme) for the last unpaid quarter and the quarter so farheld
PAYE and NIBalance of the PAYE liability account on the balance sheetnew
Corporation TaxThe estimate from docs/plans/owner-director-money.md; until it exists, Xero's Corporation Tax liability balance, labelled as suchnew
Net assets, retained profitsGET /Reports/BalanceSheet?date= (also periods, timeframe, paymentsOnly)accounting.reports.balancesheet.read (new; spelling to confirm)

Accounts are identified by account ID and type from GET /Accounts (held), never by the label in the report. The PAYE account is not a Xero system account, so the owner confirms which account it is once; the choice is stored per entity.

Method ​

Pure keyFigures(inputs, today) in src/rules/key-figures.ts: takes each figure already in pence and returns the lines and the "cash after what is owed" total. Nothing is fetched twice: payments_aged and the VAT draft are called as functions, not re-implemented.

Limits ​

  • Starling's balance includes Spaces only if the feed does (QD-10).
  • VAT so far this quarter assumes nothing else is received or paid before the quarter ends; the forecast (section 3) covers the rest.
  • PAYE is whatever Xero holds: we do not run payroll (docs/not-doing.md).
  • The Corporation Tax figure is an estimate owned by the other plan.

3. Cash-flow forecast, 13 weeks ​

What the owner sees ​

text
FEAW SERVICES LTD: cash forecast, 13 weeks from 28 Sep 2026
Lowest point £9,480.30 in the week of 14 Dec 2026. Your buffer is £5,000.00:
the forecast stays above it throughout.

Week of     Money in    Money out   Closing      What drives it
28 Sep     £2,400.00   £1,210.00   £25,500.55   Opening £24,310.55; subscriptions
5 Oct      £6,000.00   £7,242.20   £24,258.35   VAT £5,400.00 (7 Oct); Amex £1,842.20
12 Oct     £3,500.00   £2,915.40   £24,842.95   Bills from 3 suppliers
19 Oct         £0.00   £7,550.00   £17,292.95   PAYE £1,850.00; salaries £4,200.00; rent £1,500.00
...        (weeks 5 to 11 in the full reply)
14 Dec       ...         ...        £9,480.30   Lowest point
21 Dec       ...         ...       £11,905.30

Not included: sales not yet invoiced, bills not yet in Xero, the Sep-Nov VAT
return (due 7 Jan 2027, after the horizon).

Data sources ​

  • Opening cash: Starling balance today (the bank, not Xero), the same figure as key figures. Amex is not cash: its statement balance is a payment on its due date.
  • Receipts: open sales invoices (payments_aged), less unallocated credit.
  • Payments: open bills (payments_aged).
  • Tax: dates from the deadline radar (src/rules/deadlines.ts); amounts from key figures and the VAT derivation.
  • Payment history: paid sales invoices for the last 12 months (GET /Invoices with Statuses=PAID, paged; FullyPaidOnDate; held scope).
  • Bank history: 6 months of Starling lines (SPEC-003 sources).

Method ​

All in pure src/rules/cash-forecast.ts and src/rules/recurring.ts. Weeks run Monday to Sunday, London dates, week 1 is the current week.

  1. Receipts. Each open invoice lands on its due date plus that customer's median days late over the last 12 months (at least 3 paid invoices; otherwise the company median; otherwise the due date). An already-overdue invoice lands on today plus the lateness still expected, never in the past. Invoices over 90 days overdue are left out and listed as "at risk". Foreign-currency invoices use their pound value (SPEC-006 S13).
  2. Payments. Each open bill on its due date; overdue bills in week 1. No lateness assumed (prudent).
  3. Tax.
    • VAT: the unpaid return's figure on its due date (1 month and 7 days after the quarter). For a quarter still open, the draft so far plus the VAT inside forecast receipts and payments before quarter end (cash accounting: VAT follows the money).
    • PAYE and NI: the PAYE account balance on the next 22nd, then the average of the last 3 PAYE payments seen in the bank on each later 22nd. Placed on the last working day on or before the 22nd (the weekend rule is to confirm with HMRC's guidance).
    • Corporation Tax: 9 months and 1 day after the period end, from the other plan's estimate, if inside the horizon.
  4. Recurring costs. From bank history, group lines by normalised payee (payeeKey in src/rules/outstanding.ts). A group is recurring when it has at least 3 payments at a steady interval (weekly, monthly, quarterly, within 3 days) and amounts within 10% of each other. It is projected forward at the latest amount. Payees that already have an open bill, and HMRC, are skipped so nothing counts twice. Salaries are detected the same way from net pay lines. The owner confirms the list once (stored per entity); new candidates are shown, not added, until confirmed.
  5. Roll forward. Opening plus in, less out, week by week; the lowest closing balance and its week; each week's biggest drivers named.

Limits ​

  • It is arithmetic on what is already known, not a prediction. Sales not yet invoiced, one-off costs and bills not yet entered are missing, so the forecast gets less complete further out. The reply says so every time.
  • Lateness uses history; a customer who changes habits breaks it.
  • Recurring detection misses irregular costs and annual ones with fewer than 3 years of history.
  • VAT and Corporation Tax amounts are estimates until the return or the computation is final.
  • No interest, no foreign exchange movement, no Amex spending beyond the current statement.

4. "Can I afford this?" ​

What the owner sees ​

text
A £6,000.00 dividend on 9 Oct 2026
Lowest point falls from £9,480.30 to £3,480.30 (week of 14 Dec), which is
£1,519.70 below your £5,000.00 buffer.
Retained profits in Xero are £41,200.00, so the dividend is within
distributable profits on the last balance sheet (Companies Act 2006, s830).
Tax on the dividend for you personally: see owner-director-money.

Method ​

Pure whatIf(forecast, change): adds one outflow (purchase or dividend, amount in pence, date) to the forecast and re-runs the roll-forward. For a purchase with VAT, the VAT is taken off the next VAT payment if that falls inside the horizon (cash accounting: reclaimed in the quarter it is paid). It returns the old and new lowest point, the first week below the buffer, and the first week overdrawn, if any. For a dividend, it also compares the amount with retained profits from the balance sheet, and says it is only a check against the last figures, not advice.

Limits ​

Same as the forecast. Retained profits in Xero are not the same as distributable profits once the accounts are adjusted; the reply says so. Nothing is saved and nothing is paid.

5. Month-end check ​

What the owner sees ​

text
FEAW SERVICES LTD: month-end check, September 2026
3 of 5 checks pass. 2 need you.

[x] Starling reconciled to 30 Sep: 4 lines open (press OK on 3, enter 1)
[ok] Amex statement to 12 Sep reconciled
[ok] VAT: Sep-Nov so far £3,120.00; no unmapped tax codes
[x] Overdue: 2 customers owe £5,200.00 over 30 days (chase list ready)
[ok] Deadlines: VAT return due 7 Oct 2026 (7 days); PAYE due 22 Oct 2026
Profit for September £6,450.00; forecast lowest point £9,480.30.

Method ​

Pure monthEnd(results) composes results the other tools already build: SPEC-003 bank_reconciliation_check per account, the SPEC-001 draft and its unmapped tax types, payments_aged overdue totals, deadlines_upcoming for the next 30 days, and the headline figures from sections 1 and 3. One summary, each line pass or needs you, with the tool to run next.

Limits ​

It checks, it does not fix. A month is "reconciled" only when every line to the month end is matched in Xero (SPEC-003's definition).

MCP tools sketch ​

All read-only (readOnlyHint: true), except the settings tool, which writes our own database only, never Xero.

ToolReturns
reports_profit_and_lossMonth, previous month, same month last year, year to date; largest changes; reconciliation warning
reports_key_figuresCash, card, debtors, creditors, VAT, PAYE, Corporation Tax, cash after what is owed, net assets
forecast_cash13 weekly rows, lowest point, buffer check, what is left out
forecast_what_ifBefore and after lowest point for one purchase or dividend
month_end_checkThe checklist and one headline
reporting_settingsShow or set the cash buffer, the PAYE account and the confirmed recurring list

The input never carries an entity ID the server trusts; the entity comes from the session (CLAUDE.md rule 4).

Slices ​

Ordered by value. Each is small and ends with its own exit test.

  1. Monthly P&L and key figures. reports_profit_and_loss, reports_key_figures, the two new report scopes and one reconnect. Recommended first: it answers "how are we doing?" and ties to Xero.
  2. Month-end check. Composes tools that exist; small.
  3. Forecast v1. Opening cash, invoices and bills by due date, tax dates. No lateness, no recurring costs.
  4. Forecast v2. Customer lateness and recurring costs, with the confirmed recurring list.
  5. Can I afford this? forecast_what_if and the cash buffer setting.

Acceptance tests ​

  1. P&L to the penny. Given FEAW's books, when reports_profit_and_loss runs for September 2026, then every account line and the P&L totals equal Xero's Profit and Loss report for the same period to the penny.
  2. Columns. Given synthetic Xero reports for Sep 2026 (net profit £6,450.00), Aug 2026 (£3,880.00) and Sep 2025 (£5,900.00), when the tool runs, then the headline reads "up £2,570.00 on August and £550.00 on September 2025", and the text holds no pence values.
  3. Totals that do not tie are refused. Given a report whose rows sum to £1.00 more than its Net Profit, when the tool runs, then it refuses with a plain reason and shows no figures.
  4. 30-day month. Given a sale dated 31 Aug 2026, when the P&L runs for September 2026, then August includes that sale.
  5. Key figures. Given Starling £24,310.55, Amex £1,842.20, bills £3,915.40, VAT £5,400.00 and £3,120.00, PAYE £1,850.00 and Corporation Tax £6,900.00, when reports_key_figures runs, then cash after what is owed is £1,282.95.
  6. Lateness. Given Acme's last 4 invoices were paid 5, 9, 9 and 14 days late, and an open Acme invoice of £6,000.00 due 1 Oct 2026, when forecast_cash runs on 30 Sep 2026, then the £6,000.00 lands on 10 Oct 2026, in the week of 5 Oct.
  7. Tax dates. Given a Jun-Aug VAT return of £5,400.00 and a PAYE balance of £1,850.00, when the forecast runs on 30 Sep 2026, then £5,400.00 goes out on 7 Oct 2026 and £1,850.00 on 22 Oct 2026; and a PAYE payment due on Sunday 22 Nov 2026 is placed on Friday 20 Nov 2026.
  8. Recurring, never twice. Given 4 monthly payments of £1,500.00 to "LANDLORD LTD" on the 1st, and no open bill from them, when the forecast runs, then £1,500.00 is projected on each 1st; given an open bill from the same payee for that month, then only the bill is counted.
  9. Lowest point and buffer. Given the synthetic forecast above and a buffer of £5,000.00, when a £6,000.00 dividend on 9 Oct 2026 is tested, then the lowest point is £3,480.30 in the week of 14 Dec 2026 and the reply says it is £1,519.70 below the buffer.
  10. Purchase with VAT. Given a £2,400.00 purchase including £400.00 VAT on 12 Oct 2026, and no VAT payment inside the horizon after that date, when tested, then the lowest point falls by £2,400.00.
  11. Month-end. Given 4 open Starling lines to 30 Sep and £5,200.00 over 30 days overdue, when month_end_check runs, then it shows 2 checks that need the owner, each naming the tool to run next.
  12. Isolation and read-only. Given a session for FEAW only, when any tool here asks for WealthTechPros, then nothing is returned; and no tool here calls a Xero write endpoint (checked in a unit test on the client).
  13. Pure and whole. Every function in the new src/rules/ files takes and returns whole pence; a unit test feeds fractional input and expects a thrown error. The new files join the 80% per-file coverage floor.

Decisions for the Product Owner ​

RefDecisionRecommendation
newAdd a capability for management reporting (for example CAP-03.3 under Advise, MVP or post-MVP)Add it as CAP-03.3, MVP, with slice 1 in the build order after SPEC-006
newMinimum cash bufferThe owner sets it; default suggestion £5,000.00 or one month of fixed costs, whichever is higher
newForecast horizon13 weeks, weekly; not longer, since it would rest mostly on guesses
newP&L basisAccruals (as the accounts), cash basis on request
newOpening cash from the bank or from XeroThe bank (Starling), with Xero's figure and the difference shown
newStore the confirmed recurring list and PAYE account per entityYes, a small table under RLS; nothing else stored
newScopes accounting.reports.profitandloss.read and accounting.reports.balancesheet.read, one reconnectYes, in the same reconnect as SPEC-005 and SPEC-006
newDividend check against retained profitsShow it as a check with the s830 citation, clearly not advice

Sources ​

Checked 2026-09-30.

A forecast run makes about 10 Xero calls plus paged invoice reads per entity, well inside those limits.