jaz-clio 5.4.4 → 5.4.6

package/assets/skills/jobs/references/bank-recon.md

@@ -1,236 +1,235 @@
-# Bank Reconciliation Catch-Up
-
-Clear unreconciled bank statement entries by matching them to existing transactions, creating missing ones, and flagging duplicates. This is the single most impactful thing you can do for book accuracy — a clean bank recon means cash is right, and cash being right means everything else has a fighting chance.
-
-**CLI:** `clio jobs bank-recon [--account "DBS Current"] [--period 2025-01] [--json]`
+# Bank Reconciliation
+
+> Clear unreconciled bank statement entries by matching, creating, or flagging. Highest-leverage book-accuracy job in Jaz — clean cash means everything else has a fighting chance. Driver tool: `generate_bank_recon_blueprint`.
+
+## Tools, recipes, calculators this job uses
+
+### MCP tools — discovery + auto-match
+- **`generate_bank_recon_blueprint(period: <YYYY-MM>, currency: <base>)`** — step 0: emit phased recon checklist.
+- **`list_bank_accounts()`** — step 1: pull all bank-type CoA accounts (per `jaz-api/SKILL.md` rule 18: GET `/bank-accounts` returns flat array `[{...}]`, NOT the standard paginated `{ data, totalElements, totalPages }` shape — normalize before consuming).
+- **`search_accounts(filter: {accountType: {eq: 'Bank Accounts'}})`** — step 1 alternative: same data via standard CoA-search envelope if downstream wants pagination.
+- **`search_bank_records(accountResourceId: <id>, status: 'UNRECONCILED', valueDateRange: {from, to}, limit: 200, sort: 'valueDate:asc')`** — step 2: per-account work queue.
+- **`search_bank_records(accountResourceId: <id>, status: 'POSSIBLE_DUPLICATE')`** — step 3: handle dups FIRST or you'll double-create reconciling them.
+- **`view_auto_reconciliation(bankAccountResourceId: <id>, recommendationType: 'MAGIC_MATCH' | 'MAGIC_RECONCILE_WITH_CASH_TRANSFER' | 'MAGIC_RECONCILE_WITH_BANK_RULE' | 'MAGIC_QUICK_RECONCILE')`** — step 4: READ-ONLY auto-match suggestions. Does NOT write. NOTE: documented 500 quirk on high-volume accounts — see error table.
+- **`search_cashflow_transactions(filter: {organizationAccountResourceId: <bank-id>, totalAmount: {eq: <amt>}, valueDate: {between: [<-3d>, <+3d>]}})`** — step 5 manual match: search book-side transactions for the same amount within ±3 day window.
+
+### MCP tools — execute reconciliation (NOT idempotent — see error table)
+- **`apply_bank_rule(actionShortcutResourceId: <rule-id>, businessTransactionResourceIds: [<bank-entry-ids>])`** — step 4: rule-driven recon (async; returns jobId).
+- **`quick_reconcile(bankAccountResourceId, journalsForReconciliation: [...])`** — step 4: bulk async (max 500 per call); returns jobId.
+- **`reconcile_invoice_receipt(...)`** — step 4: 1:1 match of bank entry to AR invoice.
+- **`reconcile_bill_receipt(...)`** — step 4: 1:1 match to AP bill.
+- **`reconcile_direct_cash_entry(...)`** — step 4: bank entry to a single cash-in / cash-out line.
+- **`reconcile_cash_journal(...)`** — step 4: bank entry to a multi-line cash journal.
+- **`reconcile_manual_journal(...)`** — step 4: bank entry to a manual journal.
+- **`reconcile_cash_transfer(...)`** — step 4: inter-account transfer.
+
+### MCP tools — create missing transactions
+- **`mcp magic create --file <pdf>` / `create_business_transaction_from_attachment(...)`** — step 6 path B: OCR + autofill bill or invoice from receipt PDF/JPG.
+- **`create_cash_in_entry(...)` / `create_cash_out_entry(...)`** — step 6 path C: bank fees, interest, FX charges that have no source document.
+- **`create_bank_rule(...)`** — preventive: build a rule for any recurring pattern you handled this run (subscription, rent, utility) so it auto-applies next time.
+
+### MCP tools — verification
+- **`generate_bank_recon_summary(period_end, accountResourceId)`** — step 7: per-account formal recon statement.
+- **`generate_bank_recon_details(period_end, accountResourceId)`** — step 7: line-level recon detail for audit pack.
+- **`generate_bank_balance_summary(period_end)`** — step 8: book balance vs bank statement balance per account.
+
+### CLI tools — bulk auto-match cascade (offline)
+- **`clio jobs bank-recon match --input <records.json> --tolerance 0.01 --date-window 14 --max-group 5 --json`** — the 5-phase cascade matcher (Phase 1 exact 1:1 hash join, Phase 2 fuzzy 1:1 greedy with weighted scoring, Phase 3 N:1, Phase 4 1:N, Phase 5 N:M). Returns matches sorted by confidence — feed each into the appropriate `reconcile_*` tool. See `bank-match.md` for the full algorithm.
+
+### Cross-references
+- Within an engagement: invoked from `practice/references/monthly-close.md` step 3 (mandatory pre-close gate). Practice playbook reads `CLIENT.bank_accounts[]` for the per-account loop.
+- Sibling job: `bank-match.md` (the cascade matcher algorithm + scoring weights). Practitioner-facing recon step always invokes `bank-match` for any account with > ~10 unreconciled items.
+- API rules: `jaz-api/SKILL.md` rules 18 (bank-accounts envelope), 26 (cash entries `accountResourceId` shape), 50a (search query DSL), 124 (recon NOT idempotent).
 
 ---
 
-## Phase 1: Identify Bank Accounts
-
-List all bank accounts in the org. If `--account` is specified, filter to that one. Otherwise, reconcile all of them.
-
-### Step 1: List bank accounts
+## Step 0 — Emit blueprint
 
 ```
-GET /api/v1/bank-accounts?limit=100&offset=0
+generate_bank_recon_blueprint(period: '2025-01', currency: <CLIENT.base_currency>)
 ```
 
-Or via CoA search (more reliable — gives you the resourceId directly):
+## Step 1 — Discover bank accounts
 
-```
-POST /api/v1/chart-of-accounts/search
-{
-  "filter": { "accountType": { "eq": "Bank Accounts" } },
-  "sort": { "sortBy": ["name"], "order": "ASC" }
-}
-```
-
-**What you get:** A list of bank-type CoA accounts with `resourceId`, `name`, `currencyCode`. You need the `resourceId` for every subsequent step.
-
----
+For multi-org agents: invoke `list_bank_accounts()`. For each account: `{resourceId, name, currencyCode, openingBalance, currentBalance}`. Per rule 18, normalize the flat-array response. Use `search_accounts(filter: {accountType: {eq: 'Bank Accounts'}})` if you also need full CoA metadata (parent group, etc.).
 
-## Phase 2: Pull Unreconciled Items
+If `--account "DBS Current"` flag was passed: filter by `name == 'DBS Current'` first, then run the rest of the playbook on that account only.
 
-For each bank account, pull all unreconciled bank records. This is your working list.
+## Step 2 — Per-account work queue
 
-### Step 2: Search unreconciled bank records
+For each bank account `B`:
 
 ```
-POST /api/v1/bank-records/{accountResourceId}/search
-{
-  "filter": {
-    "status": { "eq": "UNRECONCILED" },
-    "valueDate": { "between": ["2025-01-01", "2025-01-31"] }
-  },
-  "sort": { "sortBy": ["valueDate"], "order": "ASC" },
-  "limit": 1000
-}
+search_bank_records(
+  accountResourceId: B.resourceId,
+  status: 'UNRECONCILED',
+  valueDateRange: { from: '2025-01-01', to: '2025-01-31' },
+  limit: 200,
+  sort: 'valueDate:asc'
+)
 ```
 
-**Omit the `valueDate` filter** if you want to see ALL unreconciled items regardless of date. For a catch-up, you usually want everything.
+Omit `valueDateRange` for full catch-up across all open periods. Paginate via `offset` if `totalElements > 200`. Each row: `{resourceId, valueDate, netAmount, extContactName, description, balance}`. `netAmount > 0` = cash-in; `< 0` = cash-out. `extContactName + description` are the highest-signal match clues.
 
-**What to check:**
-- Count of unreconciled items — this is your work queue
-- Any items older than 60 days are red flags (investigate immediately)
-- `netAmount` positive = cash-in, negative = cash-out
-- `extContactName` and `description` are your best clues for matching
+Flag any item older than 60 days as red — surface to practitioner.
 
-### Step 3: Check for possible duplicates
+## Step 3 — Handle duplicates FIRST
 
 ```
-POST /api/v1/bank-records/{accountResourceId}/search
-{
-  "filter": { "status": { "eq": "POSSIBLE_DUPLICATE" } },
-  "sort": { "sortBy": ["valueDate"], "order": "ASC" },
-  "limit": 1000
-}
+search_bank_records(accountResourceId: B.resourceId, status: 'POSSIBLE_DUPLICATE', limit: 200)
 ```
 
-**Handle duplicates first.** If two bank feed entries have the same date, amount, and description, the system flags them as `POSSIBLE_DUPLICATE`. Review and archive the genuine duplicates before proceeding — otherwise you'll create double entries trying to reconcile them.
-
----
-
-## Phase 3: Categorize and Resolve
+Two bank-feed entries with same `valueDate + netAmount + description` = system-flagged duplicate. Review each pair: archive the duplicate via `archive_bank_record(resourceId: <id>)` BEFORE running step 4. If you reconcile a duplicated row, you'll create double cashflow entries.
 
-Work through each unreconciled item. There are four resolution paths.
+## Step 4 — Auto-match cascade
 
-### Path A: Match to existing transaction
-
-The bank record matches an invoice payment, bill payment, or journal already in the books. This is the ideal case — the transaction exists, it just hasn't been linked to the bank record.
-
-**For large volumes:** Use `clio jobs bank-recon match --input data.json --json` to auto-match bank records to transactions before manual review. The calculator finds 1:1, N:1, 1:N, and N:M matches with confidence scores. See the [bank-match reference](./bank-match.md) for input format and algorithm details.
-
-**How to find the match manually:** Search cashflow transactions for the same amount and approximate date:
+For accounts with > ~10 unreconciled rows, use the cascade matcher first:
 
 ```
-POST /api/v1/cashflow-transactions/search
-{
-  "filter": {
-    "organizationAccountResourceId": { "eq": "<bank-account-uuid>" },
-    "totalAmount": { "eq": 2500.00 },
-    "valueDate": { "between": ["2025-01-10", "2025-01-20"] }
-  },
-  "sort": { "sortBy": ["valueDate"], "order": "DESC" },
-  "limit": 20
-}
+clio jobs bank-recon match \
+  --input recurring/monthly/<period>/bank-records-<account-name>.json \
+  --tolerance 0.01 \
+  --date-window 14 \
+  --max-group 5 \
+  --json
 ```
 
-**Tip:** Widen the date range by a few days — bank processing delays mean the book date and bank date often differ by 1-3 business days.
+Returns matches with confidence scores: `exact` (Phase 1 hash), `fuzzy-high` (Phase 2 weighted ≥ 0.85), `fuzzy-medium` (0.70-0.85), `nm-confident` (Phase 5). For each match returned:
 
-### Path B: Create missing transaction from attachment
+| Match type | Tool to invoke |
+|------------|----------------|
+| AR invoice ↔ bank cash-in | `reconcile_invoice_receipt(bankRecordResourceId, invoiceResourceId, paymentMethod, ...)` |
+| AP bill ↔ bank cash-out | `reconcile_bill_receipt(bankRecordResourceId, billResourceId, paymentMethod, ...)` |
+| Cash entry (single line) ↔ bank | `reconcile_direct_cash_entry(...)` |
+| Cash journal (multi-line) ↔ bank | `reconcile_cash_journal(...)` |
+| Manual journal ↔ bank | `reconcile_manual_journal(...)` |
+| Inter-account transfer | `reconcile_cash_transfer(...)` |
+| Bulk same-shape (>5 items) | `quick_reconcile(bankAccountResourceId, journalsForReconciliation: [...])` (async, returns jobId) |
+| Bank rule applies | `apply_bank_rule(actionShortcutResourceId, businessTransactionResourceIds: [...])` (async) |
 
-The bank record represents a real transaction, but nothing has been entered in the books yet. If you have the receipt, invoice, or bill document, use Jaz Magic to create the transaction automatically.
+For `view_auto_reconciliation` suggestions outside the cascade: invoke once per account, walk the suggestions, commit via the matching `reconcile_*`. Pure read — no execution side effect.
 
-```
-POST /api/v1/magic/createBusinessTransactionFromAttachment
-Content-Type: multipart/form-data
+## Step 5 — Manual match (residuals)
 
-Fields:
-  - sourceFile: <PDF or JPG of the invoice/receipt>
-  - businessTransactionType: "BILL" (for expenses) or "INVOICE" (for income)
-  - sourceType: "FILE"
-```
+For unreconciled rows the cascade missed:
 
-Jaz Magic handles OCR, line item extraction, contact matching, and CoA mapping. It creates a draft transaction that you review and post.
+```
+search_cashflow_transactions(
+  filter: {
+    organizationAccountResourceId: { eq: B.resourceId },
+    totalAmount: { eq: 2500.00 },
+    valueDate: { between: ['2025-01-08', '2025-01-22'] }
+  },
+  sort: 'valueDate:desc',
+  limit: 20
+)
+```
 
-**When you don't have a document:** Create the transaction manually using the appropriate endpoint (invoice, bill, cash-in, cash-out).
+Widen `valueDate` ±7 days for bank processing delays. Match candidate found → invoke matching `reconcile_*` tool.
 
-### Path C: Create cash journal for bank fees/charges
+## Step 6 — Create missing transactions
 
-Bank fees, interest charges, service charges, and similar items don't have a corresponding invoice or bill. Record them as cash-out journals.
+For unreconciled rows that have no book-side counterpart yet:
 
+**Path B — has document (PDF/JPG):**
 ```
-POST /api/v1/cash-out-entries
-{
-  "saveAsDraft": false,
-  "reference": "BANK-FEE-JAN25-001",
-  "valueDate": "2025-01-15",
-  "accountResourceId": "<bank-account-uuid>",
-  "lines": [
-    { "accountResourceId": "<bank-fees-expense-uuid>", "amount": 25.00, "type": "DEBIT", "name": "Monthly service charge — Jan 2025" }
-  ]
-}
+mcp magic create --file <invoice-or-receipt-path>
+# OR equivalent MCP call:
+create_business_transaction_from_attachment(
+  sourceFile: <base64 or upload>,
+  businessTransactionType: 'BILL' | 'INVOICE',
+  sourceType: 'FILE'
+)
 ```
+Magic does OCR + line item extraction + contact matching + CoA suggestion. Returns draft. Review, finalize via `finalize_bill` / `finalize_invoice`, then loop back to step 4 to reconcile.
 
-For bank interest earned (cash-in):
-
+**Path C — bank fees / interest / FX charges (no document):**
 ```
-POST /api/v1/cash-in-entries
-{
-  "saveAsDraft": false,
-  "reference": "BANK-INT-JAN25-001",
-  "valueDate": "2025-01-31",
-  "accountResourceId": "<bank-account-uuid>",
-  "lines": [
-    { "accountResourceId": "<interest-income-uuid>", "amount": 12.50, "type": "CREDIT", "name": "Interest earned — Jan 2025" }
-  ]
-}
+create_cash_out_entry(
+  reference: 'BANK-FEE-2025-01-15-001',
+  valueDate: '2025-01-15',
+  accountResourceId: <bank-account-id>,
+  lines: [{
+    accountResourceId: <Bank Charges expense GL>,
+    amount: 25.00,
+    type: 'DEBIT',
+    name: 'Monthly service charge — Jan 2025'
+  }],
+  saveAsDraft: false
+)
 ```
 
-### Path D: Flag for investigation
+Per rule 26: `accountResourceId` at top level is the BANK account; `lines[]` carries the offset (expense / income).
 
-Some items don't have an obvious match or explanation. Flag these for the business owner or finance manager to investigate. Common causes:
-- Personal transactions through the business account
-- Refunds or chargebacks
-- Intercompany transfers not yet recorded
-- Errors in the bank feed (rare but happens)
+For interest income: `create_cash_in_entry(...)` with `type: 'CREDIT'` line against `Interest Income`.
 
----
+After creating, loop back to step 4 to reconcile.
 
-## Phase 4: Verification
+**Preventive — build a bank rule:**
+```
+create_bank_rule(
+  name: 'Monthly DBS Service Charge',
+  matchCriteria: {description: {contains: 'service charge'}, amount: {between: [20, 30]}},
+  action: 'RECONCILE_WITH_DIRECT_CASH_ENTRY',
+  cashEntryTemplate: {accountResourceId: <Bank Charges>, ...}
+)
+```
+Next month's same charge auto-reconciles via `apply_bank_rule`.
 
-After resolving all items, verify the reconciliation is clean.
+**Path D — flag for investigation:** if no match and no source document, surface to practitioner with the `extContactName + description` and the `netAmount`. Common: personal transactions, refunds, intercompany unrecorded, bank-feed errors. Document in `ENGAGEMENT.risk_areas`.
 
-### Step 4: Re-check unreconciled count
+## Step 7 — Verify per account
 
 ```
-POST /api/v1/bank-records/{accountResourceId}/search
-{
-  "filter": { "status": { "eq": "UNRECONCILED" } },
-  "sort": { "sortBy": ["valueDate"], "order": "ASC" },
-  "limit": 1
-}
+search_bank_records(accountResourceId: B.resourceId, status: 'UNRECONCILED', limit: 1)
 ```
 
-**Target:** Zero unreconciled items for the period, or only genuine timing differences (outstanding cheques, deposits in transit that will clear next period).
-
-### Step 5: Bank balance summary
+Target: zero rows OR all remaining are documented timing differences (outstanding cheques, deposits in transit clearing next period — practitioner annotates).
 
 ```
-POST /api/v1/generate-reports/bank-balance-summary
-{ "primarySnapshotDate": "2025-01-31" }
+generate_bank_recon_summary(period_end: '2025-01-31', accountResourceId: B.resourceId)
+generate_bank_recon_details(period_end: '2025-01-31', accountResourceId: B.resourceId)
 ```
 
-**What to check:**
-- Book balance per Jaz should match the bank statement closing balance
-- Any difference should equal the sum of known timing items
-- Zero unreconciled difference = clean recon
+Save both to `recurring/monthly/<period>/bank-recon-<account-name>.{json,details.json}`. Audit-prep step 7 will require these files.
 
-### Step 6: Bank reconciliation summary report
+## Step 8 — Cross-account verify
 
 ```
-POST /api/v1/generate-reports/bank-reconciliation-summary
-{ "primarySnapshotDate": "2025-01-31" }
+generate_bank_balance_summary(period_end: '2025-01-31')
 ```
 
-This gives you the formal reconciliation statement showing: opening balance + cash in - cash out = closing balance, with the reconciling items listed.
+Per account: `bookBalance == bankStatementBalance ± documentedTimingDifference`. Discrepancy = unreconciled item missed → loop back to step 2 for that account.
 
 ---
 
-## Bank Recon Checklist (Quick Reference)
-
-| # | Step | Phase | What |
-|---|------|-------|------|
-| 1 | List bank accounts | Identify | Get all bank-type CoA accounts |
-| 2 | Pull unreconciled items | Pull | Search by status = UNRECONCILED |
-| 3 | Check duplicates | Pull | Review POSSIBLE_DUPLICATE items |
-| A | Match to existing | Resolve | Link to existing invoice/bill/journal |
-| B | Create from attachment | Resolve | Use Jaz Magic for documents |
-| C | Create cash journal | Resolve | Bank fees, interest, charges |
-| D | Flag for investigation | Resolve | Unexplained items |
-| 4 | Re-check count | Verify | Should be zero (or timing items only) |
-| 5 | Bank balance summary | Verify | Book balance = bank statement |
-| 6 | Reconciliation report | Verify | Formal reconciliation statement |
-
----
+## Common error classes and recovery
 
-## Tips for SMBs
+| Source | Error | Recovery |
+|--------|-------|----------|
+| `view_auto_reconciliation` | 500 on high-volume account | Documented quirk — service can OOM on accounts with thousands of unreconciled rows. Workaround: invoke per-period (`valueDateRange: {from, to}`) instead of all-time, OR fall back to `clio jobs bank-recon match` cascade which doesn't hit this endpoint. |
+| `view_auto_reconciliation` | 404 | Endpoint not enabled for the org's plan tier. Use cascade matcher only. |
+| `quick_reconcile` | PARTIAL_SUCCESS jobId | Async result. Poll `search_background_jobs(filter: {resourceId: {eq: <jobId>}})` until terminal. Read `data[0].errorDetails[]` for per-row failures; loop back to step 4 for the failed rows. |
+| `quick_reconcile` / `reconcile_*` | (any) — NOT idempotent (rule 124) | On 500 / network error, do NOT retry. Confirm reconciled state via `view_auto_reconciliation` OR `search_bank_records(status: 'RECONCILED')` first. |
+| `reconcile_invoice_receipt` | 422 `invoice_status_invalid` | Matched invoice still DRAFT. `finalize_invoice(resourceId: <id>)` first. |
+| `reconcile_invoice_receipt` | 422 `amount_mismatch` | Bank amount ≠ invoice balance. Either partial payment (post via `create_invoice_payment` with partial amount, then reconcile), or wrong match (revisit step 4/5). |
+| `apply_bank_rule` | 422 `rule_action_unsupported` | Rule's configured action doesn't match the bank entry shape (e.g., rule expects positive amount, entry is negative). Edit the rule via `update_bank_rule`. |
+| `create_cash_out_entry` | 422 `lock_date_violated` | `valueDate` in locked period. Lift lock via `update_account` lockDate, post, re-lock. |
+| Step 7 `unreconciledCount > 0` after step 6 | (residual misses) | Surface to practitioner with categorized residual ("3 bank charges to expense via path C, 1 unidentified deposit pending client query"). Document in `ENGAGEMENT.risk_areas`. Do NOT progress to monthly-close step 4 with open items. |
 
-**Do this weekly, not monthly.** A weekly 15-minute recon is far easier than a monthly 3-hour catch-up. Monday morning is ideal — reconcile the prior week's bank activity before the new week starts.
+---
 
-**Set up bank rules for recurring items.** If you pay the same rent, subscription, or utility every month, create a bank rule to auto-categorize it. This eliminates the most repetitive part of recon.
+## Tips
 
-```
-POST /api/v1/bank-rules
-```
+- **Weekly cadence beats monthly catch-up.** Monday-morning 15-min recon vs end-of-month 3-hour scramble. Recipe + cascade matcher amortize across short queues much faster.
+- **Bank rules are the highest-ROI investment.** Every recurring transaction (rent, subscription, utility) handled this run = a one-line `create_bank_rule` away from never seeing it again.
+- **Aspire + Airwallex direct feeds eliminate CSV imports.** No file step before step 2.
+- **Common bank-fee account suggestions:** `Bank Charges` / `Bank Fees` (Operating Expense), `Interest Expense` (for overdraft / loan interest paid to bank), `Interest Income` (savings / deposits), `Foreign Exchange Gain/Loss` (for FX conversion spreads).
 
-**Use bank feeds if available.** Aspire and Airwallex direct feeds auto-import bank records daily. This eliminates the CSV import step entirely.
+---
 
-**Don't let it pile up.** The longer a bank record sits unreconciled, the harder it is to figure out what it was. After 90 days, you're essentially doing forensic accounting. Stay current.
+## Cross-references back to engagements
 
-**Common SMB bank fee accounts:**
-- Bank Charges / Bank Fees (operating expense)
-- Interest Expense (for overdraft/loan interest)
-- Interest Income (for savings/deposit interest)
-- Foreign Exchange Gain/Loss (for FX conversion fees)
+- `practice/references/monthly-close.md` step 3 — invoked for every bank account in `CLIENT.bank_accounts[]`. Practice playbook owns the per-account orchestration.
+- `practice/references/quarterly-gst.md` step 3 — same recon job, scoped to the quarter; F5 Box-1 cash receipts must reconcile against bank cash-in totals.
+- `practice/references/annual-statutory.md` step 3 — final pre-FYE recon. Output feeds into `audit-prep.md` step 7 (NON-NEGOTIABLE deliverable: `unreconciledCount == 0` per account).