From c40724eae6d56b327cd3c1d13d44a23a0dc91589 Mon Sep 17 00:00:00 2001 From: Claudiu Farcas Date: Sun, 21 Jun 2026 15:11:14 +0300 Subject: [PATCH] Refine reconciliation descriptions in documentation and tests for clarity on cash checks --- README.md | 11 +++++++---- skills/xtb-portfolio-review/scripts/main.py | 14 +++++++------- skills/xtb-wealthfolio-export/scripts/main.py | 14 +++++++------- test_portfolio.py | 9 +++++---- 4 files changed, 26 insertions(+), 22 deletions(-) diff --git a/README.md b/README.md index 81a9ef5..0a39618 100644 --- a/README.md +++ b/README.md @@ -101,7 +101,8 @@ An XTB report is an `.xlsx` file with a fixed layout: - `Cash Operations` — every cash flow: stock purchases/sales, deposits, withdrawals, dividends, dividend tax, free-funds interest, currency conversions. Each trade row carries a comment like `OPEN BUY 6 @ 301.50` or `CLOSE SELL 2 @ 100.00`, and the - sheet ends with a `Total` row (the broker-reported ending cash balance). + sheet ends with a `Total` row. That `Total` is the final cash left in the account, + not the value of stocks or ETFs. Two quirks the code handles explicitly: @@ -278,7 +279,8 @@ The generated review HTML is a single offline file. It includes: - **Realized P/L** prefers the broker's `Closed Positions` `Profit/Loss` column; when that is absent, it falls back to **FIFO lot matching** from CLOSE trades. - **Cash flows** are categorized (deposits, withdrawals, interest, dividends, dividend tax, - FX fees, invested, proceeds) and reconciled against the broker's `Total` (ending cash). + FX fees, invested, proceeds). The report then checks whether its calculated ending cash + matches XTB's `Total` row, which is the final cash left in the account. - **Performance** combines **live market value** (or cost basis fallback) with cash to give portfolio value, total gain, total return %, money-weighted return (XIRR), and income yield. XIRR uses external deposits/withdrawals plus terminal portfolio @@ -327,8 +329,9 @@ only used for inline `BUY`/`SELL` commissions. Pure-cash rows use the `$CASH-

Reconciliation

{_kv_table(recon_rows)} -

XTB "Total" row reflects ending free cash; reconciled against computed cash balance.

+

This check makes sure the report read your cash movements correctly. XTB's "Total" row is the cash left in your account at the end of the period, not the value of your stocks or ETFs. The report calculates the same cash balance from deposits, withdrawals, trades, dividends, fees, and taxes, then compares both numbers.

diff --git a/skills/xtb-wealthfolio-export/scripts/main.py b/skills/xtb-wealthfolio-export/scripts/main.py index 0ddd29e..8fc2b40 100644 --- a/skills/xtb-wealthfolio-export/scripts/main.py +++ b/skills/xtb-wealthfolio-export/scripts/main.py @@ -1535,12 +1535,12 @@ TERM_TOOLTIPS = { "Pricing coverage": "How many holdings use live prices versus cost fallback values.", "Cost fallback tickers": "Tickers valued at cost because a trusted live price was unavailable. Their real market value may be higher or lower.", "Cost fallback positions": "Positions valued at cost because a trusted live price was unavailable. Their real market value may be higher or lower.", - "Reconciliation": "A check that computed ending cash matches the broker's reported cash total.", - "Cash reconciliation": "A check that computed ending cash matches the broker's reported cash total.", - "Computed ending cash": "Computed ending cash is the cash balance calculated from all cash operations in the report.", - "Broker 'Total' (cash)": "Broker 'Total' (cash) is the cash total reported by XTB at the end of the Cash Operations sheet.", - "Difference": "Difference shows computed cash minus broker-reported cash. A value near zero means the calculation reconciles.", - "Status": "Status tells you whether the reconciliation check passed or needs attention.", + "Reconciliation": "A check that the report's cash math matches the final cash amount shown by XTB.", + "Cash reconciliation": "A check that the report's cash math matches the final cash amount shown by XTB.", + "Computed ending cash": "The cash balance calculated by this report from deposits, withdrawals, trades, dividends, fees, and taxes.", + "Broker 'Total' (cash)": "The final cash amount shown by XTB. This is cash left in the account, not the value of your stocks or ETFs.", + "Difference": "Computed cash minus XTB cash. A value close to zero means the cash movements were read correctly.", + "Status": "Shows whether the cash check passed or whether the numbers need attention.", "Gross income": "Dividends plus interest before dividend tax.", "Dividend tax": "Tax withheld from dividend payments.", "Net income": "Income remaining after dividend tax.", @@ -2035,7 +2035,7 @@ def build_html_report(

Reconciliation

{_kv_table(recon_rows)} -

XTB "Total" row reflects ending free cash; reconciled against computed cash balance.

+

This check makes sure the report read your cash movements correctly. XTB's "Total" row is the cash left in your account at the end of the period, not the value of your stocks or ETFs. The report calculates the same cash balance from deposits, withdrawals, trades, dividends, fees, and taxes, then compares both numbers.

diff --git a/test_portfolio.py b/test_portfolio.py index da4d373..8385e04 100644 --- a/test_portfolio.py +++ b/test_portfolio.py @@ -1306,10 +1306,11 @@ class TestHtmlReport: ) assert "A ticker is the short code used by markets and brokers" in html assert "realized_pl means realized profit or loss" in html - assert "Computed ending cash is the cash balance calculated from all cash operations" in html - assert "Broker 'Total' (cash) is the cash total reported by XTB" in html - assert "Difference shows computed cash minus broker-reported cash" in html - assert "Status tells you whether the reconciliation check passed" in html + assert "cash balance calculated by this report from deposits, withdrawals, trades" in html + assert "cash left in the account, not the value of your stocks or ETFs" in html + assert "Computed cash minus XTB cash" in html + assert "whether the cash check passed" in html + assert "This check makes sure the report read your cash movements correctly" in html # ---------------------------------------------------------------------------