Spreadsheet Model Auditor

Models look right when you read them cell by cell. Structural errors -- a SUM that stopped one row short, a formula overwritten with a typed number in month 7, a rate hardcoded in one copy of a formula -- are invisible to eyeballing and are exactly what gets people fired over a board number. Do not audit by reading the grid. Run the script, which reads every formula, then spend human judgment on what a script cannot know: whether the assumptions are sane.

Workflow

1. Get an .xlsx

• Excel file: use it directly (.xlsx or .xlsm). Legacy .xls: convert first with soffice --headless --convert-to xlsx file.xls.
• Google Sheets: File > Download > Microsoft Excel (.xlsx). Read references/google-sheets.md for which Sheets functions survive export and what to check manually.
• CSV is not a model. It has no formulas; there is nothing structural to audit. Ask for the workbook.

2. Run the script

python3 scripts/audit_xlsx.py model.xlsx --json audit.json --md audit.md

Add --recalc when the report says cached values: NO. That happens when the file was written by a script, a BI export, or any tool that does not calculate: openpyxl can read formulas from any file, but stored results exist only if Excel (or LibreOffice) calculated and saved it. --recalc runs soffice --headless --convert-to xlsx on a copy so error, footing, and stale-value checks can run. Without LibreOffice the script still runs every formula-based check and says which value checks it skipped -- never report "no errors" for a check that was skipped.