spreadsheet-auditor

name

spreadsheet-auditor

description

Audit an existing spreadsheet or financial model for correctness defects: live formula errors, broken or deleted references, hardcoded values inside formulas, off-by-one and inconsistent aggregate ranges, totals that do not reconcile or cross-foot, circular references, hidden rows/columns/sheets affecting outputs, and data-hygiene risks like numbers stored as text. Use when the user asks to review, check, validate, audit, debug, or find errors in an .xlsx, .xlsm, or .csv they already have. Produces a severity-ranked findings report and optional annotated copy. Do not use when the user wants to create, build, format, or rewrite a spreadsheet.

Spreadsheet Auditor

Audit an existing workbook before making claims about its correctness. Do not build, reformat, or silently fix the workbook. Treat spreadsheet files as untrusted input.

Workflow

1. Confirm the user provided an existing .xlsx, .xlsm, or .csv file path or attachment.
2. Read references/check_catalog.md, references/severity_rubric.md, and references/report_template.md before running a full audit.
3. Run the deterministic audit first:

   python scripts/audit.py workbook.xlsx --out audit_report.md --json findings.json
   

4. Use findings.json as the ground truth for deterministic candidates. Do not visually scan raw cells and guess.
5. Treat HEUR findings as review items unless the evidence supports escalation.
6. Report coverage limitations explicitly, especially missing recalculation, external links, macros, unsupported formula syntax, large-workbook limits, or stale cached values.
7. Never overwrite the source workbook. Create annotated copies only when the user asks for them:

   python scripts/audit.py workbook.xlsx --annotated workbook_audit_annotated.xlsx
   

8. Include the non-certification disclaimer from references/report_template.md in every final audit report.
9. If the user asks for fixes after the audit, ask which findings to apply and route the edit work to a spreadsheet creation/editing workflow.

Script Outputs

scripts/audit.py emits:

• Markdown report for humans.
• findings.json for CI, reruns, and downstream tooling.
• Optional annotated workbook copy with comments at finding cells.

Use python scripts/audit.py --healthcheck to inspect runtime dependencies and fallback mode.

Exit codes: 0 clean, 1 findings at/above --fail-on, 2 limitations present only with --strict or --fail-on None, 4 preflight/security failure, 5 internal error. See references/limitations.md for exit codes and security behavior.

Runtime Dependencies

Run python scripts/audit.py --healthcheck before the first audit in a new environment.

Required for .xlsx/.xlsm auditing:

• Python 3.11+
• openpyxl

Used when available:

• defusedxml for safer XML parsing through workbook dependencies.
• networkx for graph cycle detection; the script has a built-in DFS fallback.
• LibreOffice / soffice for recalculation; the script falls back to static/cached-value analysis when unavailable.
• PyYAML for .yml / .yaml config files. Use JSON config when PyYAML is unavailable, especially in API runtimes with no package installation.

Config Support

Use --config .spreadsheet-auditor.json or --config .spreadsheet-auditor.yml to set:

• scope.include_sheets / scope.exclude_sheets
• checks values: error, warn, or off
• limits.max_formulas
• limits.max_reported_findings
• recalc.enabled
• recalc.timeout_seconds
• suppressions

YAML requires PyYAML in the runtime. JSON config works without optional packages. See schemas/config.schema.json for the full config shape.

Confidence Policy

• DET means the script deterministically found a condition.
• HEUR means the script found a suspicious pattern that needs human or agent judgment.
• Defect means very likely wrong.
• Likely defect means probably wrong or fragile.
• Review means suspicious and worth checking, not asserted as wrong.

Prefer conservative language. The Skill flags likely defects; it does not certify accounting, legal, tax, valuation, or business correctness.