The Interface Layer, part 2: handing a seam over safely

Part 1 ended with a page: the seam inventory, every place a person carries information between systems, with the judgment inside each seam named. This chapter is about what to do with it. It applies to any implementation of the loop, ours included, and it is written so that a company could follow it with its own team.

Which seams first

The inventory tempts you toward the biggest number. Resist it for a week. The first seams you hand over teach the company how this works, and a bad first seam teaches the wrong lesson. Pick by these five criteria, in this order.

The judgment repeats. Look at the judgment column. A seam where the decision has the same shape every time ("which purchase order does this invoice belong to") is ready. A seam where every case is a different kind of exception is not ready; it is where you go third, once the layer has memory of the house rules.

The input is at least half structured. E-invoices, bank exports, order confirmations, delivery notes with a fixed layout. Photos of handwritten notes are possible and come later.

A wrong decision can be undone. A mis-matched invoice caught at approval costs a minute. A wrong tax declaration costs a quarter. Start where mistakes are cheap, because there will be mistakes, and the point of the first seam is to see them.

The hours are real. Among the seams that pass the first three tests, take the one with the most monthly hours. Nobody should have to squint to see the effect.

The owner is willing. The person who crosses that seam today will design the handover with you, and will become its approver. If they dread it, pick another seam and come back. Chapter 1 named them; this is where their judgment gets written down.

Two seams that usually pass all five: supplier invoices into the ledger, and client status questions answered from operational systems. Two that usually fail the third test and should wait: anything filed with the tax authority, and anything that sends money.

One seam, decomposed

Take the supplier-invoice seam at the distributor from chapter 1 and lay it on the loop.

Read. The invoice itself, structured if it came through e-invoicing, scanned if it came by email. The purchase orders open for that supplier. The delivery notes of the last weeks. The rule the office manager stated once: "this supplier's freight line goes to logistics, not to goods."

Resolve. Which supplier record, given that the name arrived with a new spelling. Which purchase order, given that the amounts match two of them and only one is for the delivered quantity. Which cost centers, per line, given the rule above.

Propose. The ledger entry, line by line, with each value pointing at its source: this total from page one of the invoice, this quantity from the delivery note, this cost center from the stated rule. And a plain-language note where something is off: "quantity on the invoice exceeds the delivery note by twelve units."

Confirm. The office manager sees the proposal and the evidence, corrects the one line that needs it, approves. Thirty seconds instead of eleven minutes, and the mistake she catches is the system's, not hers.

Record. The entry is written to the accounting program, the invoice is filed and linked, the supplier record gains the new spelling as an alias, and the correction she made becomes a memory: next time, the system proposes it her way.

Every seam in the inventory decomposes like this. Doing it on paper for the first two seams, with the owner, is an afternoon, and it is the design document.

Which step needs which model

Not every step of the loop needs the same machinery, and most of the cost of a bad implementation is using the expensive tier for work a cheaper one does better. Assign each step a tier.

Tier zero, no model. Parsing the structured e-invoice fields. Looking up the supplier by tax id. Exact matching of an invoice number. Validation rules the accounting program already has. Scheduling. This tier is exact, free, and should carry everything it can.

Tier one, small and fast. Classifying a document ("this is a credit note, not an invoice"). Extracting fields from a semi-structured PDF. Producing the shortlist of candidate purchase orders. Deciding which of three fixed actions a message asks for.

Tier two, the strongest model. Reading a half-legible scan. Choosing between two candidates when the amounts match both. Writing the note that explains the discrepancy. Handling the case nobody wrote a rule for.

The discipline is a single rule: push every step down to the cheapest tier that meets the precision bar, and measure the bar, which is chapter 3. In the invoice seam above, roughly everything is tier zero and one except the ambiguous match and the explanation. That is typical, and it is why the layer is affordable.

Where the confirmation boundary goes

The default is simple and should be written down before anything runs: anything that leaves the company or changes a record of consequence waits for a person. Sending an email to a supplier, posting an entry, changing a payment field, deleting a document. Reading, resolving, and drafting run freely; acting waits.

The default is not the end state. Autonomy is earned per class of decision, never granted per system.

A class of decision is "matching an e-invoice to a single open purchase order with an exact amount", not "invoices". For each class, the approver's own behavior tells you when it is safe: after a run of approvals with no corrections, long enough to have seen the month's variety, that class can move to automatic with a sample reviewed. One in ten at first; the sample is where drift will show up. Classes that fail the diagram's question, the irreversible and the outbound, stay at propose-and-confirm permanently. Their value is in the proposal, not in the autonomy.

Two rules that hold at every level of autonomy. A proposal with no evidence is not a proposal. If the system cannot point at the document and the field a value came from, it must say so and stop, and the design should make silent guessing impossible rather than discouraged. And the "I could not determine this" path must exist and must be visible: a queue of unresolved items that a person works through daily. The size of that queue is a health signal, and each item resolved is a candidate for a new memory or a new rule.

The mechanics that prevent the classic failures

Idempotency. Every write is keyed by an external identifier: the invoice number and supplier, the message id from the e-invoicing system, the order number. Running the same seam twice, because a schedule fired twice or a person clicked twice, must produce nothing new. Duplicates are the fastest way to lose trust, and they are entirely preventable.

Least privilege, assuming a leak. The layer gets read access broadly and write access narrowly. Credentials are scoped to the job, rate-limited, and stored as if they will one day be exposed, because some credential somewhere always is. A key that can read invoices should not be able to email clients.

Memory with an owner. Rules stated by the approver ("treat these two suppliers as one") become memory the system applies. Memory needs an owner and a list; unowned memory is how a wrong rule from March quietly shapes every decision in June.

An audit trail from day one. Who approved what, on what evidence, when. Less for the auditor than for the Tuesday when a number is wrong and the person who has to find out why has ten minutes.

The rollout

Shadow. For two to four weeks the system produces proposals and the person keeps doing the seam the old way. At the end of each day, compare. This is where you discover the spelling variants, the rule nobody stated, the one supplier whose invoices always look wrong. Nothing has been risked, and the design document gets its corrections.

Assisted. The person now works from the proposals: reviews, corrects, approves. This is the state most seams live in for a long time, and it is already most of the value: the hours drop, the errors are caught at approval, the judgment is captured as memory every time a correction is made.

Sampled. For the classes that pass the decision above and have earned it through the approval record, automatic with a reviewed sample. This is the state that returns the last of the hours, and it is entered one class at a time, never by flipping a switch on the whole seam.

Two to six weeks per seam is a realistic pace with a willing owner. Faster usually means the shadow stage was skipped, and the shadow stage is where the cheap mistakes are found.

What goes wrong

Automating the exceptions first. They are the most annoying part of the person's day, so they attract attention. They are also the part with the least pattern. Do them third.

Silent drift. A supplier changes its invoice layout; a portal renames a field. The parser at tier zero starts producing wrong values with full confidence. The sampled review and the unresolved queue exist to catch this; if nobody looks at them, nothing catches it.

Proposal fatigue. If the approver sees forty low-stakes confirmations a day, they stop reading them, and the boundary becomes theatre. Move the safe classes to sampled autonomy and keep the human attention for the decisions that need it.

Tool sprawl. Each new source connected is a new seam with the layer itself. Connect what the inventory ranked, in that order, and stop when the hours are back.

What the handover produces

At the end of one seam handed over you have: a design document that names the judgment; a memory of the house rules in the owner's words; an approval record that shows, class by class, what the system gets right; an unresolved queue that shows what it does not; and an approver whose day is shorter. You also have the raw material for the only question that matters next: did it work, and how would you know? That is chapter 3.