Beancount Reconcile

beancount-reconcile

Reconcile one account against one statement period: find every discrepancy between the ledger and the statement, and — only after the user confirms — append the missing transactions and a period-end balance assertion that proves the account ties out.

This skill exists because reconciliation is the deterministic trust check for a ledger, and doing it by hand is tedious and error-prone: statement sign conventions differ from ledger conventions, pending-vs-settled timing shifts dates, and the only real proof of correctness is a balance assertion that beancount itself verifies. The skill normalizes the statement, diffs it against the ledger, classifies each discrepancy, and lands a balance assertion whose success (via the root-ledger check) is the reconciliation's definition of done.

Prefer bea

Read beancount-init's references/bea-cli.md before running ledger commands: it defines explicit root/destination paths, JSON batches, checks, and safe retries. Without bea, use beancount-init's references/compatibility.md.

Use bea for approved account opens, missing-transaction batches and balance assertions. The skill retains normalization, discrepancy classification and the tie-out. An explicit opening adjustment may use add balance --pad-from only on a first reconcile with no prior assertion and an accepted opening gap.

Scope — what this skill does and does not touch

Does: compare one account to one statement; append missing transactions and one period-end balance assertion; report everything else it finds.

Does not: edit or delete existing entries. Duplicates, suspect entries (in the ledger but not on the statement), and amount mismatches are reported for the user to fix by hand — this skill only appends. It never touches option, plugin, or include directives, and never reconciles more than one account per run.

Read references/statement-formats.md before parsing any statement and references/matching.md before classifying discrepancies. Both encode edge cases that are easy to get wrong.

Workflow

Five phases, in order: Discover → Normalize → Match → Propose → Verify.

1. Discover

Learn the ledger and the reconciliation target before reading the statement.

Find beancount files in the working directory:

fd -e beancount -e bean . | head -20
# fallback: find . -maxdepth 4 \( -name '*.beancount' -o -name '*.bean' \)

The "main" file is the one with option/plugin/include directives at the top, or the largest with open directives.

Then establish, in order:

• Target account — the single account being reconciled (e.g. Assets:Bank:Checking, Liabilities:CreditCard:Amex). If the user named an account or a bank, map it to the open account. If ambiguous, ask — do not guess which account a statement belongs to.
• Account type — is the target an Assets or a Liabilities account? This determines the statement sign convention (see Normalize). Read it from the account name.
• Config block — a comment block at the top of the main file starting with ;; beancount-reconcile config. If present, it records the statement's date format and sign convention per account so re-runs don't re-detect. Re-read it rather than re-detecting.
• Prior reconciliation point — the most recent balance assertion for the target account. Its date and amount are the trusted starting point; you only need to reconcile forward from there.
• Append target — the file where the target account's transactions live (the main file, or an included sub-file, possibly year-bucketed).

Report the target account, its type, and the prior balance assertion (if any) to the user before continuing, so a misdetection is caught early.

Persist the contract as a config block on the main file — but only as part of the confirmed append (show it in the Propose phase; never write it before the explicit yes):

;; beancount-reconcile config
;; date_format: MDY
;; Assets:Bank:Checking sign: asset      ; +deposits, -withdrawals
;; Liabilities:CreditCard:Amex sign: liability  ; -charges, +payments
;; append_target: ./ledger.beancount

2. Normalize

Turn the statement into normalized lines. Read references/statement-formats.md first. In brief:

• Accept a CSV export or pasted PDF text. Extract three things: the statement period (start and end dates), the ending balance, and the transaction lines (date, amount, description).
• Map every amount to the ledger's sign convention for the target account:
  • Asset account: money in = +, money out = −.
  • Liability account: a charge = − (you owe more), a payment = + (you owe less).
• Statements vary (separate debit/credit columns, signed amounts, MDY vs DMY dates, running-balance columns). When the sign or date convention is ambiguous, ask — never guess; a flipped sign silently corrupts the reconciliation.

If the statement's ending balance or period bounds can't be found, ask for them. They are required — the balance assertion depends on them.

3. Match

Diff the normalized statement lines against the ledger's postings to the target account within the period. Read references/matching.md first for the full algorithm and tolerances. The classes:

Matching order: exact (date + amount) first, then a windowed pass (amount equal within ±N days, description similar), then a near-miss pass over the leftovers (similar description + date window with different amounts → amount-mismatch; one line matching two+ postings → duplicate). Anything unmatched on either side falls into one of the classes above. When a match is ambiguous, ask rather than force it.

4. Propose

Show the user the reconciliation, then ask before writing. Never write before an explicit yes — this is the user's financial source of truth.

Present, in this exact order:

1. Target file — one explicit path.
2. Diff report — a section per class with counts, listing each line and the proposed action.
3. New open directives — only if a proposed entry needs an account that doesn't exist yet.
4. Proposed transactions — for each missing-in-ledger line, one transaction, formatted exactly as it will appear. Attach import-id per beancount-import's references/dedup.md and preserve pending/uncertain ! flags in the JSON batch. The target-account posting is the statement amount (in ledger sign); the other leg is categorized from the ledger's own payee history (see below). Format the entry, don't just describe it.
5. Tie-out calculation — the query that produced the numbers and its output (see "Reproducible tie-out arithmetic" below). The ledger balance, projected balance and residual (statement ending − projected ledger, signed) come from that output, not from prose arithmetic.
6. Proposed balance assertion — only when the executed residual is exactly zero and no suspects, mismatches, or duplicates remain.
   • Ties out: propose the balance assertion at the statement's ending balance, dated the day after the statement's last day (see "Balance-assertion date" below).
   • Does not tie out: do not propose a passing-looking assertion, and never append a failing one — a permanently-failing balance directive would break the user's bea check on every future run. Instead show the signed residual and tie it to the unresolved items: the residual equals the net of the reported suspects/mismatches/duplicates, or is unexplained when there are none. Never invent a fee, pad, or adjustment to absorb it. Tell the user to resolve those (by hand — this skill won't edit existing entries) and re-run. Offer, only if they explicitly ask, to append the assertion as a commented-out ; 2026-06-01 balance … tripwire.
7. A clear yes/no prompt.