supplier-price-variance-alert

---
name: supplier-price-variance-alert
description: Checks every supplier invoice line against the price last paid, and against what the invoice is legally required to show, so a creeping price rise or a line failing to match its own description doesn't reach a recipe cost unnoticed. It flags any line priced differently from the last invoice, and any invoice missing a detail HMRC requires. Use every time an invoice arrives, before its prices feed dish-cost-builder.
---

# Catching a price that moved before it moves your margins

Give this the current invoice and the price you paid last time for each item on it. Get back every line where the price changed, by how much, and whether the invoice itself is valid enough to rely on.

## What it does

1. **Check the invoice carries what HMRC requires before trusting a price on it.** A valid VAT invoice must show "a description sufficient to identify the goods", "the quantity", "the unit price", and "the amount payable, excluding VAT" (VAT Notice 700/21, 4.1). Missing a unit price or quantity means it can't be checked at all.
2. **Match each line to the same item on the previous invoice**, by description and supplier, not invoice order; suppliers reorder lines.
3. **Compare VAT-exclusive unit prices only**, never inclusive against exclusive, which produces a false 20% "rise" out of nowhere.
4. **Flag the size of any change**, in percentage and absolute terms, and flag a rise hidden in a pack-size change: a case cut from 6×2kg to 6×1.8kg at the same price is a real rise even though the total looks unchanged.
5. **Check delivery matches description.** Goods sold by description must correspond with it: "there is an implied term that the goods will correspond with the description" (Sale of Goods Act 1979, section 13). A line invoiced as one cut, grade or brand but delivered as another is grounds for a credit, not just a query.

## Then it checks

1. Every line has a unit price, quantity and VAT-exclusive amount; missing ones are flagged, not estimated.
2. Every comparison is VAT-exclusive against VAT-exclusive, never mixed.
3. Every flagged variance shows percentage and absolute change, naming the previous invoice compared.
4. A pack-size change is checked for a hidden unit-price rise, not just the case price.
5. No variance is marked "resolved" without a dated supplier reply.

Any check fails: redo once. Failed twice: say what's wrong and stop.

## Rules

- Public information only. Never invent a fact, number or quote, or a previous price with no earlier invoice; mark it "no prior price."
- Anything sent in someone's name says whose name it is.
- Never compare a VAT-inclusive price to a VAT-exclusive one and report the gap as real.
- Never close a flagged variance as agreed without a dated supplier response.
- Working document for the owner to check against their own invoices and purchase history, and their accountant or solicitor where a dispute becomes contractual. Not legal or accountancy advice.

## Built from
- HMRC, "Record keeping (VAT Notice 700/21)", https://www.gov.uk/guidance/record-keeping-for-vat-notice-70021, published 26 September 2013, updated 18 March 2024, read 4 November 2026: section 4.1's valid-invoice checklist, steps 1 and 3.
- Sale of Goods Act 1979, section 13, https://www.legislation.gov.uk/ukpga/1979/54/section/13, read 4 November 2026: the implied term goods must correspond with description, step 5.

# supplier-price-variance-alert

## You are given
The current invoice: supplier, date, and one row per line with description, quantity, unit, unit price, VAT-exclusive amount and VAT rate. The most recent previous invoice(s) for the same supplier, same shape. Where known, the pack size (units per case, weight per unit) for any case-sold line.

## Produce
Write into a `./supplier-price-variance-output/` folder:

1. `invoice-validity.csv`: `invoice_ref`, `line_ref`, `description_present`, `quantity_present`, `unit_price_present`, `vat_exclusive_amount_present`, `vat_rate_present` (all `yes`/`no`), `valid_for_comparison` (`yes` only if all five are `yes`).
2. `price-variance.csv`: `line_ref`, `description`, `current_unit_price_ex_vat`, `previous_unit_price_ex_vat`, `previous_invoice_ref`, `change_absolute`, `change_percent`, `pack_size_changed` (`yes`/`no`), `true_unit_price_rise` (recalculated per base unit when pack size changed), `flagged` (`yes` when `change_percent` exceeds 3% either way, or pack size changed).
3. `no-prior-price.csv`: `line_ref`, `description`, `current_unit_price_ex_vat`, `reason` (`no previous invoice on file for this item`). Never carried into `price-variance.csv` as a zero-change row.
4. `description-match-check.csv`: `line_ref`, `invoiced_description`, `delivery_note_description_if_supplied`, `match` (`yes`/`no`/`not checked, no delivery note supplied`), `notes`.
5. `gaps.md` - numbered list of: every `valid_for_comparison: no`; every `flagged: yes` line; every row in `no-prior-price.csv`; every `match: no` row.

## Rules
- Codex matches, compares and flags. It never assumes a previous price when none is on file, and never treats a VAT-inclusive figure as comparable to a VAT-exclusive one.
- If either invoice only shows a VAT-inclusive figure, flag `VAT-exclusive price not confirmed` rather than comparing anyway.
- Line matching is by description and supplier, not row position; a reordered line must not produce a false variance.
- A pack-size change always triggers recalculation to a common base unit before judging the true price, never on case price alone.
- British English, GBP, DD Month YYYY dates. No em dashes.
- Every file ends with: this is a working document prepared for the owner to check against their own supplier invoices and purchase history, and for their accountant or solicitor to check where a dispute over price or description becomes a contractual question. It is not legal or accountancy advice.

## Return
The absolute path and row count of each file. Lines failing the validity check and why. Lines flagged for a price variance, with the largest rise named. Lines where a pack-size change hid a true rise. Lines with no prior price. Description mismatches found. The `gaps.md` item count.