---
name: "tax_ready_document_filing"
description: "Turn a messy pile of invoices and receipts into a tax-ready archive: extract vendor, invoice number, date, and amount from PDFs and receipt photos into a reviewed manifest, then file everything into a Year/Quarter/Category tree with safe renaming, dry-run-first copying, and an audit-friendly summary. Use when someone needs to organize financial documents for tax time, prepare a receipts packet for an accountant, or tame a folder of unsorted invoices and receipts."
---

# Tax-Ready Document Filing

## Purpose
Take unsorted invoices, receipts, and receipt photos and produce an archive a tax preparer can actually use: every document extracted to a manifest, renamed consistently, filed into a predictable tree, and summarized by quarter and category. Originals are never touched. The filing script copies, never moves or deletes, and dry-run is the default. Anything the extractor cannot read confidently goes to a human review queue, never into the archive under a guessed name.

## Workflow
1. **Intake.** Put every document in one `inbox/` folder. Separate personal and business expenses at the door; mixed documents get flagged, not silently assigned. Photos of receipts are fine. If a document is missing (replacement needed), add it to the missing-documents list in the summary instead of pretending it exists. See `references/retention.md` for what must be kept and for how long.
2. **Extract.** Run `bin/taxfile_extract.py inbox/ --out manifest.csv`. It reads native-text PDFs (pdfplumber, pypdf fallback), OCRs images when tesseract is installed, and pulls vendor, invoice number, date, and amount with regex patterns from `references/extraction-patterns.md`. Output rows carry a confidence level; anything below threshold is marked `REVIEW` with the reason.
3. **Review.** Open `manifest.csv` and fix every `REVIEW` row by hand: vendor aliases (see `references/extraction-patterns.md` for the alias table pattern), missing dates, ambiguous amounts. Assign the business category on each row (see `references/naming-and-folders.md` for the category list). If a field is genuinely unreadable, leave it blank with a note; never guess it.
4. **File, dry run first.** Run `bin/taxfile_file.py manifest.csv --dest Tax2026 --dry-run` and read the planned actions. When the plan looks right, run again with `--apply`. The script copies files into `Tax2026/<YYYY>/<Qn>/<Category>/`, renames them to `YYYY-MM-DD_Vendor_INV-ID_$Amount.ext`, appends `-02`, `-03` on collisions, and never overwrites. Rows missing a date or amount file into `_Review/` instead of the tree. See `references/naming-and-folders.md` for the convention.
5. **Packet.** `taxfile_file.py` writes `summary.md`: document counts, totals by quarter and category, the `_Review` list with reasons, and the missing-documents log. Hand this, plus the manifest, to the accountant. This skill prepares documents; it is not tax advice.

## Output Contract
- `manifest.csv`: one row per document with columns `source_path, vendor, invoice_id, doc_date, amount, currency, category, confidence, needs_review, notes`. The invoice date comes from the document, never the file system date.
- `Tax<YYYY>/` tree: `Year/Quarter/Category/` folders with consistently renamed copies.
- `review/` (inside the tree): `review.csv` of everything that failed extraction or was missing fields, with reasons; originals untouched.
- `summary.md`: totals by quarter and category, review queue, missing documents, retention reminder.
- `undo-log.csv`: every applied copy with source and destination, so a botched run can be reversed by deleting the dest files.
- `manifest.csv` and `summary.md` stay with the archive so the numbers trace back to the documents.

## Operating Rules
1. Never invent a number, date, vendor, or category. An unverified field stays blank and flagged.
2. The invoice date on the document is the date, not the download date or file date. Digital photos are dated by the receipt they show.
3. Copy, never move, never delete. Originals stay exactly where they were.
4. Dry-run before apply, every time. Read the plan.
5. Filenames never overwrite. Collision suffixes only.
6. A review queue is a feature, not a failure. Anything unclear goes there with a reason.
7. Personal expenses are excluded explicitly with a note. Mixed-use items are prorated with the percentage written down.
8. This skill organizes documents for taxes; it does not give tax advice. The packet goes to an accountant or preparer.
9. Write like a person wrote it. No em dashes, no marketing phrasing, no filler.