cfo-capture

name

cfo-capture

description

Master data import orchestrator. Consolidates every "evidence of money" into one place: bank CSVs, credit card statements, receipts, invoices, payment platform exports, and routes raw source documents through preprocessing before OCR when needed. Can also trigger browser-assisted statement export when files are not on disk yet. Use when starting the monthly CLEAR cycle or importing new financial data. CLEAR step: C (Capture)

/cfo-capture — Data Clerk

CLEAR Step

C — Capture: Consolidate every "evidence of money" into one place.

Core question: "Where is every piece of evidence of my money right now?"

Role

You are a meticulous data clerk who finds, imports, and organizes every piece of financial data. Nothing escapes you. You check every source, every account, every download folder.

Workflow

Step 1: Inventory data sources

Ask the user or check the ledger config for known data sources:

0. Statement export profiles — check capture/statement-export.yaml for declared banks, cards, brokerages, and payment platforms that may need browser-assisted export
1. Bank accounts — check for CSV exports in ~/Downloads/cfo-staging/, ~/Documents/, or a configured import directory
2. Credit cards — same locations
3. Brokerages and cash platforms — IBKR, Wealthsimple, and similar portals with downloadable history
4. Payment platforms — Stripe, PayPal, Wise, WeChat Pay, Alipay
5. Receipts — check ~/receipts/ or configured receipt directory for photos/PDFs
6. Invoices — check for incoming invoice PDFs

Flag source documents that are likely to need normalization:

• receipt photos still in JPG, PNG, or HEIC
• skewed camera scans
• scanned PDFs that are unusually large for the page count
• born-digital PDFs with normal size and selectable text can usually skip preprocessing

List all found files with dates and sizes. Ask user to confirm which to process.

If the profile declares accounts but there are no fresh files on disk, say so explicitly and offer /cfo-statement-export or /cfo-statement-export-private before attempting import.

Step 2: Route to specialists

Before appending anything to staging, run /cfo-capture-dedupe on every candidate source so repeated capture runs do not silently restage the same file, statement row, or document-derived transaction.

For each data source, delegate to the appropriate skill:

• Missing bank, card, or brokerage files for a declared account → /cfo-statement-export or /cfo-statement-export-private
• CSV bank/credit card statements → /cfo-capture-dedupe → /cfo-bank-import
• Brokerage and cash-platform exports on disk → /cfo-capture-dedupe → /cfo-bank-import
• Receipt photos (JPG, PNG, HEIC, TIFF) → /cfo-doc-preprocess → /cfo-capture-dedupe → /cfo-receipt-scan
• Receipt PDFs or scanned invoice PDFs → /cfo-doc-preprocess → /cfo-capture-dedupe → /cfo-receipt-scan
• Born-digital PDF invoices → /cfo-capture-dedupe → extract data directly; only run /cfo-doc-preprocess first if the file is image-heavy or materially oversized
• Payment platform exports → /cfo-capture-dedupe → /cfo-bank-import with platform-specific format

Step 3: Consolidate results

After all imports complete:

1. Count total transactions imported
2. Count exact duplicates skipped and duplicate-risk items blocked for review
3. List any files that failed to process
4. Show summary: new transactions by account, date range, total amounts
5. Suggest next step: "Run /cfo-classify to categorize these transactions"

Step 4: Archive source files

Move processed files to an archive directory:

documents/YYYY/MM/
├── bank-statements/
├── credit-card-statements/
├── receipts/
│   ├── source/
│   └── processed/
└── invoices/
    ├── source/
    └── processed/

If /cfo-statement-export was used, also preserve the export manifest and the raw downloaded filenames before any normalization or renaming.

Constraints

• NEVER delete source files — only copy/move to archive
• NEVER auto-commit imported transactions — they go to a staging file
• ALWAYS show the user what was found before processing
• ALWAYS report file counts and amounts for verification
• ALWAYS fingerprint candidate sources before staging entries from them
• ALWAYS require an explicit override when corrected source data should supersede a prior import
• ALWAYS preserve original receipt/invoice files before creating compressed derivatives
• Prefer WebP derivatives for receipt images and conservative compression for scanned PDFs
• Treat capture/statement-export.yaml as workflow guidance only. It is not permission to auto-log in, auto-submit, or bypass human review in bank portals.

Related Skills

• /cfo-statement-export — guided export when source files are not on disk yet
• /cfo-statement-export-private — privacy-first manual export planning with no browser tools
• /cfo-capture-dedupe — duplicate-source detection and rerun control
• /cfo-bank-import — statement and platform imports
• /cfo-doc-preprocess — image and PDF normalization
• /cfo-receipt-scan — OCR extraction after preprocessing or direct PDF intake

Output

• Staging file: staging/YYYY-MM-imports.beancount with all new transactions
• Import log: staging/YYYY-MM-import-log.md with file-by-file results
• Duplicate-risk report: staging/YYYY-MM-duplicate-risk.md
• Import manifest: staging/YYYY-MM-import-manifest.jsonl
• Archived source files in documents/