User Guide — Cash Recovery Engine

This guide walks a finance or revenue-operations user from zero to a prioritized collections worklist in a few minutes.

1. The 30-second mental model

You have overdue invoices and limited collector time. Every invoice falls into one of four buckets:

Segment	Meaning	What to do
Persuadable	A call meaningfully raises the chance it pays	Work it first — this is where hours convert to cash
Self-Cure	Will likely pay on its own	Send an automated reminder; don't spend a collector on it
At-Risk	Shaky, and not very responsive to a call	Structured follow-up / payment plan
Critical	Low chance to pay and low movability	Escalate (senior collector, dispute, credit hold)

The engine's whole job is to find the Persuadable invoices with the highest cash-per-hour and put them at the top of the queue.

2. Run the demo

node run.mjs

This trains the engine on resolved history, scores a live demo ledger of 900 open invoices ($19.0M), and writes three deliverables to reports/:

• collections-worklist.csv — the ranked worklist (open in Excel/Sheets).
• executive-summary.md — a one-page summary for leadership.
• engine-output.json — the full structured result for downstream systems.

The demo packs an 80-hour budget (≈ two collectors for a week) and projects $0.52M of cash accelerated from just 61 invoices — see the generated reports/executive-summary.md for the live figures.

3. Use the live tool

Open public/tool.html in any browser.

• Capacity dial — set the collector-hours you have this period. The worklist

and every KPI re-optimize instantly.

• KPI cards — projected cash accelerated, lift vs. FIFO at equal hours,

invoices on the worklist, and total open AR.

• Recovery curve — cumulative cash recovered as the budget grows, for the

engine vs. FIFO vs. largest-balance vs. random. The gap above the grey lines is the cash a conventional worklist leaves on the table.

• Where the hours go — the recovery opportunity by segment.
• Download worklist (CSV) — exports exactly the queue shown, for the

capacity you dialed in.

4. Read the worklist

Each row carries the numbers a collector and a controller both need:

Column	Meaning
recovery_segment	Persuadable / Self-Cure / At-Risk / Critical
self_cure_prob	Probability it pays within the horizon with no action
uplift	Extra probability of payment if a collector works it
expected_incremental_cash_usd	amount × uplift
value_per_hour_usd	expected incremental cash ÷ estimated effort
recommended_action	The play for this segment

The queue is sorted by value_per_hour_usd — the engine's ranking key.

5. Bring your own data

When you have a real AR export, place two files under data/official/ (schema in run-deploy-instructions.md) and run node verify.mjs. The same checks then evaluate your data, and node run.mjs can be pointed at it to produce a live worklist. Until you do, treat every figure as a benchmark demonstration, not a recovery promise for your books.

6. What the numbers mean (and don't)

The verified metrics (AUC 0.817, calibration ECE 0.018, +127% cash vs. the strongest simple baseline, 2.94× FIFO) describe the engine's behaviour on the synthetic benchmark. They are not a recovery figure for your company; that requires your data and a holdout or A/B validation. See proof/LIMITATIONS.md.