| name | cfo-validate |
| description | Run bean-check plus custom validation rules on the ledger. Ensures every entry
balances, accounts exist, and no common errors are present.
Use after any ledger modification to verify integrity.
CLEAR step: L (Log)
|
/cfo-validate — Quality Control
CLEAR Step
L — Log: Ensure every entry in the ledger is valid and correct.
Role
You are the quality gate. Nothing gets committed without passing your checks.
Workflow
Step 1: Run validation helper
./bin/cfo-check ./ledger/main.beancount
./bin/cfo-check
Discovery order:
- The explicit path passed to
./bin/cfo-check
./main.beancount./ledger/main.beancount- The first
main.beancount found under the current working tree
Report any errors with file, line number, and description.
Step 2: Custom validation rules
Beyond bean-check, verify:
- Balance assertions exist for every bank/credit card account at month-end
- No orphaned accounts — every open account has at least one transaction
- No future-dated transactions (unless explicitly flagged)
- Consistent payee naming — flag variations (e.g., "Amazon" vs "AMZN" vs "Amazon.ca")
- Receipt linkage — transactions over $75 should have a receipt reference
- Tax treatment — all business expenses have tax metadata
- Flagged transactions — report any
! (flagged) entries that need resolution
- Duplicate-risk findings — surface unresolved items from the capture duplicate-risk report or manifest conflicts
Step 3: Report
VALIDATION REPORT
═══════════════════
bean-check: PASS (0 errors)
Balance checks: PASS (12 assertions, all hold)
Orphan accounts: WARN (1 account with no transactions)
Future dates: PASS
Payee names: WARN (3 inconsistent names)
Receipts: WARN (2 transactions >$75 missing receipts)
Tax treatment: PASS
Flagged: INFO (1 flagged transaction remaining)
Duplicate risk: WARN (1 corrected reimport waiting for approval)
Overall: PASS with warnings
Constraints
- Run automatically before every
/cfo-snapshot commit
- Report all issues — never silently ignore
- Distinguish ERROR (must fix) from WARNING (should fix) from INFO (awareness)
Related Skills
/cfo-capture-dedupe — emits duplicate-risk findings and import manifests/cfo-snapshot — blocked until validation results are acceptable
