# mercury-cash-reconciliation

Produces the Mercury side of a cash ledger reconciliation for one account and month, formatted as a workpaper for accountants closing books.

Skill by Mercury. Category: Documents.

## Install

Project (for this project only):

```sh
npx skills add mercurytechnologies/mercury-skills --skill mercury-cash-reconciliation
```

Works with: Claude Code, Codex CLI, Cursor, Antigravity, Copilot CLI, opencode.

Global (for every project on this machine):

```sh
npx skills add mercurytechnologies/mercury-skills --skill mercury-cash-reconciliation -g
```

Works with: Claude Code, Codex CLI, Cursor, Antigravity, Copilot CLI, opencode.

## Tags

- Runs on your computer: It runs as a program on your machine, with your access.

## Security audits

- Gen Agent Trust Hub: Pass
- Socket: Pass
- Snyk: Warn

Installs: 3. Installs counted by skills.sh. [Open on skills.sh](https://www.skills.sh/mercurytechnologies/mercury-skills/mercury-cash-reconciliation)

## Source

[Open the source](https://github.com/mercurytechnologies/mercury-skills/tree/HEAD/skills/mercury-cash-reconciliation). Checked 2026-10-10. This summary may contain AI-generated text, so it can be wrong. Check the source before you rely on it.

## SKILL.md

````markdown
---
name: mercury-cash-reconciliation
description: "Produce the Mercury side of a cash General Ledger reconciliation for a given account and period, formatted to drop into a Mercury Reconciliation Workbook."
metadata:
  version: "1.0.0"
  category: agentic
  scopes: [accounts:read, transactions:read]
  requires: [mercury-shared]
---

# Mercury Cash Reconciliation

Pulls the Mercury side of a cash General Ledger (GL) reconciliation for a target Mercury account and accounting period. Produces a workpaper block formatted to match the standard Mercury Reconciliation Workbook — GL balance vs. Mercury balance, a reconciling-items table bucketed into timing / permanent / prior-period, tickmark legend, and sign-off line.

> This skill produces only the Mercury side of the workpaper. The other half — the GL-system balance pull, accounting-tool sync, and any journal-entry adjustments — comes from your finance close process and is supplied by the user.

This skill is **read-only by default**. The optional Step 7 (memo-tagging aged items) is the only write, and only fires after explicit user confirmation.

## Parameters

| Parameter | Default | Description |
|-----------|---------|-------------|
| `accountId` | (required) | Mercury account to reconcile. If omitted, the skill lists accounts and asks. |
| `period` | Last closed month | Period to reconcile, as `YYYY-MM` (e.g. `2026-04`). |
| `priorOpenItems` | none | Optional path to a JSONL file or pasted list of items still outstanding from the prior period — used to age and resolve carry-forward items. |
| `outputDir` | `~/Downloads` | Where to save the reconciliation Markdown block and any downloaded statement PDF. |

## Execution Strategy

### Step 1: Anchor and resolve scope

```
1. Run `date +%Y-%m-%d` to get today's date.
2. IF period not provided:
       period = previous calendar month, format YYYY-MM
3. Compute:
   - periodStart = first day of period (YYYY-MM-01)
   - periodEnd   = last day of period (last calendar day)
4. Run `mercury accounts list --max-items -1 --format jsonl`.
5. IF accountId not provided:
       Show the user a numbered account list (name, kind, last4) and ask which to reconcile.
   ELSE:
       Confirm the account exists in the list. If not, stop and surface the error.
6. Capture the Mercury-reported `currentBalance` and `availableBalance` from the chosen account row.
```

### Step 2: Download the period statement (optional but recommended)

The statement PDF is the authoritative source for the bank-side closing balance the reconciliation owner ties to.

```
mercury statements download --account-id <accountId> --period <YYYY-MM> --output <outputDir>/mercury-rec-<accountSlug>-<period>.pdf
```

> Verify exact flag names with `mercury statements download --help` before first use — `--period` and `--output` are the expected shape but flag names can drift. If `statements download` is not available in your CLI build, skip this step and tie to `currentBalance` from Step 1 instead.

If the PDF downloads, extract the printed closing balance and use it as the canonical Mercury-side balance. If it doesn't, fall back to Step 1's `currentBalance` and call this out in the workpaper notes.

### Step 3: Pull the period's transactions

```
mercury transactions list \
  --account-id <accountId> \
  --start <periodStart> --end <periodEnd> \
  --max-items -1 --format jsonl \
  --transform 'transactions.#.{id,amount,postedAt,createdAt,counterpartyName,status,note,kind}'
```

Note: this call deliberately omits `--status sent` — we need pending and in-transit items to surface reconciling differences. Filter by status in the analysis step instead.

### Step 4: Bucket reconciling items

```
posted    = transactions where status == "sent"
inTransit = transactions where createdAt in period AND (status != "sent" OR postedAt > periodEnd)
pending   = transactions where status in ("pending", "processing") AND createdAt in period

# Aged carry-forward
IF priorOpenItems supplied:
    FOR EACH prior IN priorOpenItems:
        IF prior.id IN posted (i.e. it cleared this period):
            mark prior as "cleared"
        ELSE:
            carryForward.push(prior with age + 1 month)
ELSE:
    carryForward = []  # ask user to supply prior workbook for full aging
```

### Step 5: Compute the reconciliation

```
mercuryBalance   = statement closing balance (Step 2) OR currentBalance (Step 1)
inTransitTotal   = sum(abs(t.amount) for t in inTransit, with sign preserved)
pendingTotal     = sum(abs(t.amount) for t in pending, with sign preserved)
carryForwardTotal = sum(carryForward amounts)

# Adjusted Mercury balance — what the GL should reconcile to.
adjustedMercury = mercuryBalance
                  + (debits in transit / pending that haven't yet hit the bank)
                  - (credits in transit / pending that haven't yet hit the bank)
                  + carryForwardTotal

# At this stage the user supplies the GL balance from the finance close process.
# Difference = glBalance - adjustedMercury
# Any non-zero difference is a "permanent" reconciling item -- bank fees, missing entries, errors.
```

If the user hasn't supplied the GL balance, emit the workpaper with the GL row blank and a `[fill in from NetSuite]` placeholder.

### Step 6: Emit the workpaper block

Save to `<outputDir>/mercury-rec-<accountSlug>-<period>.md` and also print to the conversation.

```markdown
# Mercury Cash Reconciliation — <Account Name> (****<last4>)

**Entity:** <entity number from account, if available>
**GL Account:** [fill in from NetSuite]
**Period:** <period> (<periodStart> to <periodEnd>)
**Statement PDF:** <path or "not downloaded">
**Prepared by:** <user>  |  **Date:** <today>

## Balance summary

| Line | Amount |
|------|--------|
| GL closing balance | $[fill in] |
| Less: in-transit debits not yet posted | -$<amount> |
| Add: in-transit credits not yet posted | +$<amount> |
| Less: pending debits | -$<amount> |
| Add: pending credits | +$<amount> |
| Aged outstanding carryforward | +/-$<amount> |
| **Adjusted Mercury balance** | **$<adjustedMercury>** |
| Mercury statement closing balance | $<mercuryBalance> |
| **Difference (should be $0.00)** | **$<diff>** |

## Reconciling items

| # | Date | Counterparty | Amount | Category | Age (days) | Status | Action | Tickmark |
|---|------|--------------|--------|----------|------------|--------|--------|----------|
| 1 | ... | ...          | ...    | timing   | ...        | ...    | ...    | ✓        |
| 2 | ... | ...          | ...    | prior    | ...        | ...    | ...    | †        |
| 3 | ... | ...          | ...    | permanent| ...        | ...    | ...    | ^        |

**Tickmarks:** ✓ agreed to Mercury statement   ^ recalculated   † tied to prior period

## Sign-off

| | Name | Date |
|-|------|------|
| Preparer | | |
| Reviewer | | |
```

### Step 7 (optional, write): Tag aged carry-forward items

Only run if the user explicitly approves and there are carry-forward items aged 30+ days.

```
Prompt: "Tag {N} aged reconciling items with 'rec-aged-<period>' in their note field? (y/N)"

IF user confirms:
    FOR EACH item IN agedCarryForward:
        mercury transactions update \
          --transaction-id <item.id> \
          --note "rec-aged-<period> (carry forward {age} months)"
```

This is purely a marker so next month's run can pick the items up without re-typing them. Follow the `mercury-shared` write rules — one transaction at a time, surface errors per item, stop on 401/403.

## Example Output

```
Mercury Cash Reconciliation — Operating (****4821)
Entity: 11300   GL Account: [fill in from NetSuite]
Period: 2026-04 (2026-04-01 to 2026-04-30)
Statement PDF: ~/Downloads/mercury-rec-operating-2026-04.pdf
Prepared by: cobrien   Date: 2026-05-14

Balance summary:
  GL closing balance                                  $[fill in]
  Less: in-transit debits not yet posted              -$4,820.00
  Add:  in-transit credits not yet posted             +$0.00
  Less: pending debits                                -$1,247.50
  Add:  pending credits                               +$0.00
  Aged outstanding carryforward                       +$312.00
  Adjusted Mercury balance                            $1,247,503.21
  Mercury statement closing balance                   $1,253,258.71
  Difference                                          $0.00  ✓

Reconciling items:
  # | Date       | Counterparty       | Amount     | Category  | Age | Status   | Tickmark
  1 | 2026-04-29 | Vendor Wire Co     | -$4,820.00 | timing    |   1 | pending  | ✓
  2 | 2026-04-28 | SaaS Charge        | -$1,247.50 | timing    |   2 | pending  | ✓
  3 | 2026-02-15 | OldVendor LLC      | -$312.00   | prior     |  88 | open     | †
```

## Tips

- **Pull without `--status sent`** for this skill — pending and in-transit items are the whole point. The `mercury-shared` rule about defaulting to `sent` applies to spend-analysis skills, not reconciliation.
- The Mercury statement PDF's printed closing balance is what the reconciliation owner ties to. If you can't download it, surface that clearly and tie to `currentBalance` with a note.
- If the GL balance isn't supplied, emit the workpaper with placeholders rather than skipping — the reconciliation owner pastes the GL row in from the finance close process on their side.
- For Broker Dealer / restricted-cash subaccounts, the entity number matters for the J-file. Confirm with the user which entity context the account belongs to before emitting the workpaper.
- Aged items 60+ days old should be flagged to the user verbally, not just included in the table — they may need an adjusting entry rather than another month of carry-forward.
````

- Previous: [mercury-autocategorize-transactions](https://syn4pse.dev/terminal/mercury-autocategorize-transactions.md)
- Next: [mercury-detect-anomaly](https://syn4pse.dev/terminal/mercury-detect-anomaly.md)
- [Terminal](https://syn4pse.dev/terminal.md)
- [Suggest a change](mailto:terminal@syn4pse.dev?subject=Terminal%20suggestion)
