receipt-pile

---
name: receipt-pile
description: Turns a folder of receipt photos and PDF invoices into one spreadsheet of date, supplier, net, VAT, gross, category and source file, leaving anything unreadable blank and listed.
---

# A year of receipts turned into one spreadsheet

You point it at the folder of receipts. It gives you one spreadsheet your bookkeeper can work from, plus a named list of every file it could not read.

Run it from the folder holding the receipts:

```
codex exec -C "the folder" - < the-prompt.md
```

## What it does

1. **Count the pile before reading any of it:** list every PDF, JPG, PNG, HEIC and TIFF in the folder and its subfolders, and write filename, size and page count to `receipts-inventory.csv`. That count is the number the finished spreadsheet must reconcile to, so a file that goes missing halfway through the run cannot go unnoticed.

2. **Read the document, never the filename:** for a PDF, try the text layer first. If the PDF has no text layer it is a scan, so treat it as an image and read it visually. A file named `esso-march.pdf` may be a Shell receipt from April. The filename is a clue for the review list and is never a source of data.

3. **Pull seven fields and nothing else:** date, supplier, net, VAT, gross, category, source filename. Take the date from inside the document, using the tax point or time of supply where the document shows one and the invoice date otherwise. Never use the file's created or modified date, which is the date the photo was taken or the file was copied, not the date of the purchase.

4. **Never invent a VAT figure:** if the document prints a VAT amount, copy the printed figure exactly. If it prints a gross and a VAT rate but no VAT amount, you may derive net and VAT, and the row must be marked `derived` with the rate recorded. If it prints neither a VAT amount nor a rate, leave net and VAT blank and mark the row `no VAT shown`. A number that looks right is worse than a blank, because a blank gets checked and a plausible number does not.

5. **Reconcile every row to the penny:** net plus VAT must equal gross. Where the document also shows shipping, service or a tip, those must be inside that total too. If it does not reconcile, do not adjust any figure to make it fit. Mark the row `does not reconcile`, record all three numbers as printed, and move on.

6. **Check whether the document could actually support a VAT reclaim, and record the answer:** HMRC's manual VATREC5010 sets what a full VAT invoice must show under regulation 14(1) of the VAT Regulations 1995, including a unique sequential number, the time of supply, the date of issue, the supplier's name, address and VAT registration number, the customer's name and address, a description of the goods or services, the quantity or extent, the VAT rate and amount payable excluding VAT, and the total VAT chargeable. A retail supply of £250 or less including VAT may instead be a simplified invoice, which VAT Notice 700/21 says needs only the supplier's name, address and VAT registration number, the time of supply, a description, and for each VAT rate the total payable including VAT and the rate charged. Add one column, `vat_invoice`, holding `full`, `simplified`, or `no VAT number shown`. Do not drop the row either way. Deciding what is reclaimable is the accountant's job, not this skill's.

7. **Categorise from a fixed list agreed once, at the start:** ask for the list of categories before reading anything, or use the ones already present in last year's spreadsheet. Never invent a category to suit a receipt. Anything that does not fit goes to `Uncategorised`, which is a question for the owner, not a failure.

8. **Flag possible duplicates, remove nothing:** the same supplier, the same date and the same gross is a possible duplicate, and so is a photo and a PDF of one receipt. Flag every member of the set with a shared duplicate group number and leave all of them in the spreadsheet. A genuine second identical purchase on one day is common in a small business, so this is a question, not a finding.

9. **Deliver one file with two sheets, then the summary:** sheet one is the rows read, sheet two is every file that could not be read, with its filename and the reason, in plain words such as "photo too blurred to read the total" or "handwritten, no printed total". Then print: files in, rows complete, rows flagged, files unreadable, date range covered, and the totals for net, VAT and gross.

## Then it checks

1. Rows read plus files listed as unreadable equals the file count in `receipts-inventory.csv`. If they do not match, stop, because a receipt has been silently dropped.
2. Every row's source filename exists on disk, and no filename appears on two rows unless the file genuinely holds more than one receipt and the report says so.
3. Every row that has both a net and a VAT figure reconciles to its gross to the penny.
4. No row carries a VAT figure that was not printed on the document, unless it is marked `derived` and the printed rate is recorded alongside it.
5. Every date falls inside the period requested, and none is in the future.
6. Recompute the summary totals from the finished sheet rather than carrying them over from the reading pass, and confirm they match. A total typed by hand from a reading pass is not evidence of what is in the sheet.

Any check fails: name it, redo that step once. Failed twice: say what is wrong and stop.

## Rules
- Public information only.
- Never invent a fact, a number or a quote.
- This prepares a spreadsheet for a bookkeeper or an accountant to check. It is not tax advice, it is not a VAT return, and it does not decide what is claimable or deductible. The VAT rules it applies are United Kingdom rules, so if the receipts are not UK receipts, say so and stop before applying any of them.
- Never invent, round or back-calculate a VAT figure the document does not show. Blank and listed beats a plausible number, every time.
- Read only. Never rename, move, edit or delete a source receipt, and never delete a suspected duplicate.
- Keep the originals after the spreadsheet exists. HMRC's guidance in VAT Notice 700/21 is that you must generally keep all your business records for VAT purposes for at least six years, and a spreadsheet is not a substitute for the invoice.

## Built from
- Receiptor-AI/bookkeeping-skills, https://github.com/Receiptor-AI/bookkeeping-skills, 4 stars read from api.github.com on 7 September 2026: its `receipt-processing` skill file gave the minimum field set, the five validation checks, and the rule that a record failing a required-field check is routed to a review queue rather than having its missing data fabricated.
- openaccountant/skills, https://github.com/openaccountant/skills, 66 stars read from api.github.com on 7 September 2026: 44 open source financial skills. Took its principle that every skill must also work with no database behind it, from exported CSV files alone. Its tax categories were deliberately not taken, because they are United States categories such as IRS Schedule C and 1099 contractors.
- ComposioHQ/awesome-claude-skills, https://github.com/ComposioHQ/awesome-claude-skills, 74,627 stars read from api.github.com on 7 September 2026: its Invoice Organizer entry and skill file gave the "maintains originals" rule and the idea of producing a CSV for the accountant as the deliverable rather than a tidy folder.
- HMRC internal manual VATREC5010, "Details which must be shown on a full VAT invoice", https://www.gov.uk/hmrc-internal-manuals/vat-trader-records/vatrec5010, last updated 16 January 2025: the exact list of required fields in step 6, and the citation of regulation 14(1) of the VAT Regulations 1995.
- Record keeping (VAT Notice 700/21), https://www.gov.uk/guidance/record-keeping-for-vat-notice-70021: the £250 including VAT threshold for a simplified invoice, the shorter field list a simplified invoice needs, and the six year retention period quoted in the rules above.