tax_ready_document_filing v1.0.0

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.