tax-sort-receipts

Sort Tax Receipts

The user has downloaded receipt attachments from their email and dropped them into a receipts-to-sort/ folder inside their tax return folder. Your job is to read each file, match it to the correct category, rename it clearly, and move it to the right place.

Find the tax return folder

If the user named a specific tax return folder, use it.

Otherwise, look for the most recent tax-return-FY* folder in the current working directory.

If no tax return folder exists, there's nothing to sort yet — tell the user to prepare their tax return first (they just ask, e.g. "do my 2024-25 tax", which runs the au-tax-return skill).

Discover the structure

1. Find all CSV files in the tax return folder (including subfolders like rental/). These are your sources of truth — deductions.csv, rental-schedule.csv, or any other CSV the skill created.

2. Find all receipts-to-sort/ folders — there may be one at the top level (for work deductions) and one under rental/ (for rental property). Check all of them.

3. Find all receipts/ folders and their existing subfolder structure. Don't assume specific folder names — the skill creates category folders like D5-work-related/, plant-equipment/, expenses/, etc. depending on the type of deduction. Work with whatever exists.

Process

For each receipts-to-sort/ folder found:

1. Read the relevant CSV(s) to understand what items have been identified and which categories they belong to.

2. List all files in the receipts-to-sort/ folder.

3. For each file, read/examine it to determine:

   • What vendor it's from
   • What item or service it's for
   • The dollar amount
   • The date

4. Match it to an item in a CSV by comparing vendor, amount, and date. If there's a clear match, move the file to the correct receipts/{category}/ subfolder with a clear name: {vendor}-{brief-description}-{YYYYMMDD}.{ext}

5. If the receipt contradicts the CSV (e.g., the CSV says "laptop" but the PDF is actually a router, or the amount is different), flag it to the user: "The CSV has this listed as 'Scorptec laptop — $XXX' but the receipt says 'TP-Link Deco XE75 (mesh router) — $XXX'. Should I update the CSV to match the receipt?" Always trust the actual receipt over the CSV entry.