Right about every field, wrong about which document

The situation

Ravensgate Stores issues a purchase order as one PDF file.

When it changes that order, its system rebuilds the whole bundle: the original order first, then the amendment letter, then any earlier amendments. One file, one filename.

That is not carelessness. It is how their system produces a complete record, and their own buyers find it handy. It is also the trap in this lesson.

• 4 December. RVG-51188 is issued. 33,600 pieces of HM-2264, ex-factory 28 March. Ex-factory is the date the goods must be finished and ready to leave the factory gate.
• 19 December. Amendment 1 is issued. The quantity goes up to 42,000. Ex-factory is pulled forward to 14 March. It arrives as an eleven-page PDF: pages 1 to 6 are the original order, page 7 is blank, pages 8 and 9 are the amendment letter, and pages 10 and 11 are the terms.

Halmside's extractor read that bundle and returned a quantity and an ex-factory date. Both were correct copies of a real Ravensgate document. Both were wrong.

Why it read the original

The amendment is a letter. It has a paragraph, three lines of changes and a signature.

The original order has a table: a header row, a grid of line items, a totals row. It is laid out exactly like every other purchase order the system has ever seen.

So when it was asked for a quantity, it found a quantity. When it was asked for an ex-factory date, it found a date. It found both on pages 1 to 6, because that is where a purchase order looks like a purchase order.

Nobody looked, and that is the mechanism

Here is the part that makes this a general problem rather than a story about one bad afternoon.

On 4 December the extractor returned 33,600 and 28 March. Those were right. On 19 December it read the amended bundle and returned 33,600 and 28 March again.

Nothing on Hadeel's screen changed. No value moved. No exception fired. The only signal a person ever gets that an amendment has arrived is a value changing, and the value did not change.

An amendment that changes nothing on your screen is the dangerous one. It is dangerous for exactly that reason: it looks like an amendment that changed nothing.

What it cost

It surfaced on 21 February. Ravensgate's merchandiser, Noreen Calmady, asked which vessel the 14 March hand-over was booked on. Twenty-one days to find 8,400 pieces and fourteen days.

The extra 8,400 pieces need 11,256 metres of fabric, at a consumption of 1.34 metres a piece. Pellworm Mills quotes 32 days as standard and 18 days if the order is expedited, meaning pushed to the front of the queue for extra money. The premium is USD 0.41 a metre.

Two lines in that table need a word of explanation. A split shipment is one order sent in two consignments instead of one, and the forwarder charges for the second. A shade concession is a discount the buyer takes when a second dyeing run comes out slightly off the first one's colour.

The order is 42,000 pieces at FOB USD 9.15. FOB means the price with the goods loaded on the vessel, with sea freight and insurance still to be paid by the buyer. It was costed at a 12.2% margin, which is USD 46,884.60 of profit.

So one extraction that was right about every character cost 20.3% of the whole order's margin.

Air freight was priced and refused. The fabric could not arrive before day 18 whatever anyone paid, which left three days to cut, sew and pack 8,400 pieces. There was no expensive way out, only a cheap one taken too late.

It is a machine, not an accident

Halmside then went back over the whole season. Ravensgate issued 31 amendments. Nine of them changed a field the factory plans from. Six of those nine were invisible in exactly this way: the rebuilt bundle put the superseded document first, the extractor read it, and no value moved on anybody's screen.

Five were caught by a person before they had cost the full amount, at a mean of USD 2,935.00 each. One was not.

Season total: USD 24,180.36 across six amendments, a mean of USD 4,030.06 each. Hold that figure. Lesson 5 uses it, and lesson 7 prices a check against it.

Provenance is a field, and it was thrown away

The repair took Naji an afternoon, and what he found is the reason this lesson exists.

The extractor already knew. Inside, it tracked the page each value came from, because it had to in order to find them. It threw that away on the way out, because the output had no field for it. The output listed quantity, date, price, code. It did not list where this came from. That is what provenance means: the record of which document, and which page, a value was read off.

Course 10.1 lesson 1 defines a field as a claim made under a definition at a moment. This is the same idea with its teeth showing: a fact you have no field for cannot be wrong, and it cannot be checked either. There was no provenance error in Halmside's system before that afternoon, because there was no provenance.

The new output carries three more values on every extracted field:

1. Which page of the file the value was read from.
2. What the document on that page calls itself: a purchase order, an amendment, a confirmation.
3. What date that document carries.

Then one rule, which is arithmetic rather than judgement: if the file contains a document dated later than the document this value came from, hold the whole extraction for a person. Across the season's 31 amendments that rule fires 9 times and is right 9 times. It is not guessing about content. It is comparing two dates.

Act as a records and document-control specialist in a garment factory. I am going to give you what my document reader returned from one buyer file, and I want you to test the SOURCE of each value rather than the value itself. Here is what I have. The file: [FILENAME], [NUMBER] pages, received [DATE]. What the reader returned: [PASTE EVERY EXTRACTED FIELD AND ITS VALUE]. What the reader recorded about where each value came from, if anything: [PASTE PAGE NUMBERS, DOCUMENT TITLES, DOCUMENT DATES — OR WRITE 'nothing' IF IT RECORDED NONE]. What my order record currently says: [PASTE MY QUANTITY, EX-FACTORY DATE, PRICE, DELIVERY TERMS, COLOUR AND SIZE SPLIT]. Do the following. First, list every extracted value for which I cannot say which page it came from, and mark those as unverifiable rather than as correct. Second, tell me for each value whether it agrees with, contradicts or is silent about what my order record already says, and treat 'agrees exactly with what I already had' as a warning rather than as reassurance, because an amendment that changes nothing on my screen is invisible to me. Third, list the questions I must answer by opening the file myself: how many separate documents are in it, what each one calls itself, what date each one carries, and which is the newest. Fourth, give me a single yes or no on whether any value in this extraction could have come from a document that a later document in the same file supersedes. Fifth, write me the one-line rule I should put into my intake checklist so this test runs every time without me thinking about it. Do not guess at any value I have not given you, and say plainly where you have too little to answer.

Lesson 3 turns to the number the extractor prints beside every value it returns, and to what happens when a factory treats it as a probability.