Staple instruction manual

What Staple is for, and what to do first

Staple answers two questions that decide whether a repair is finished on the first visit. Which parts should the technician's truck carry for tomorrow's booked calls, and which technician should take each call? When the stock lives on the trucks, those are one decision, so Staple scores them together.

Every number in it comes from repair history I invented: 160,000 jobs over 1,096 days from 1 Nov 2023, across 6 appliance types and 30 technicians. The last 92 days are held back. Each method learns from the earlier days only, and is then scored on the held-back days as if they had not happened yet. That is a back-test, and it is the same test I would run first on real history.

What to do first. The report is one screen with two sides. On the left is the plan for one invented day: read the three steps across the top, then the to-do list, which says what each team does before 08:00. On the right is the proof: that day against the current way, then the evidence from all 92 held-back days. The next section walks through every part of the screen.

Hover over anything with a dotted underline, or anything that turns your pointer into a question mark. The hint shows the figures behind it and the query they come from. A blue ? opens this manual at the word it explains. Under every chart, "Show the numbers" opens the table the chart is drawn from.

How to read the plan screen

The report is one screen with two sides, and on a desktop each side scrolls on its own, so the page itself never does. The left side is the plan for one invented day. The right side is the proof that the plan beats the current way. Choosing a technician anywhere on the left lights up their route, their row and their load sheet, and shows their card on the right. Every page opens light. The Dark mode button at the top switches it, and your browser remembers the choice.

Across the top

Three steps say what Staple does, in order: Claude codes every booking, Staple plans the trucks, and people act before 08:00. Under them, the day buttons pick one of the most recent 7 held-back days. They are not picked by hand. A ✚ marks a technician who called out sick and a ⚠ a truck that broke down, so the days with surprises show before a click. The page opens on the most recent day on which a sick call and a breakdown both moved calls to other trucks.

The left side, top to bottom

• The day's four tiles: booked calls, the share expected fixed on the first visit, second visits avoided, and parts moved overnight. Each compares the plan with the current way on the same day.
• AI at booking: how many bookings Claude coded at once, and a card for every booking it was unsure of. A card shows the customer's words, Claude's first reading with its confidence, the one question it asked, the answers offered with the one taken in yellow, and the code the call runs on. Where the answer changed the carry list, the card shows what the first guess would have loaded and what the truck loads now.
• To do before 08:00: every action, grouped by who takes it. The next section lists every kind. Clicking an item lights up its truck and opens, on the right, the evidence behind that kind of action.
• 07:00 and after: each sick call and breakdown, every call it moved, from whom to whom, and its first-visit chance before and after. A moved call can use only the parts its new truck already carries.
• Routes and the board: the map of the twelve zones beside a row for each technician from 08:00 to 17:00. Each block is a call, shaded by its first-visit chance, darker for likelier. The switch shows the plan as made at night or the day as it ran. On the day as it ran, a sick technician's row is hatched, a broken truck's row stops at a ⚠ marker, a moved call is outlined and tagged with the technician it came from, and on the map a dashed line joins it to its new truck. A yellow corner marks a call Claude asked about, a hatched block a call added on the day, a red underline a visit missing a needed part, and ▲ a call escalated to urgent.
• Load sheet: the chosen truck's list for the parts room tonight. Each row says put on or take off, the part and its made-up cost, its worth, and the booked calls behind it with each one's chance of needing it. Under it, the parts kept aboard: those tomorrow's calls may need, and a count by appliance of the stock kept for unplanned calls.

The right side

First, the day against the current way, with both replays on Claude's codes and the same surprises. Then the chosen technician's card: their appliances, how often they fix each first time, and how fast. Then the evidence from all 92 held-back days, which runs on the call-taker's booked codes so it measures the planning apart from the reading. Each card ends with what a fleet does with it. The last two cards say how a fleet would adopt Staple, and what this does and does not show.

Every to-do, and who does it

What the numbers mean

The four figures across all held-back days

They head the right side, under the day's comparison, and run on the call-taker's booked codes.

Fixed on the first visit is the share of all held-back calls that Staple's dispatch fixes on the first visit. A call fixes first time only when the truck holds every part it needs, and the technician's own success rate on that appliance then decides it. A call rolled to tomorrow counts as not fixed. The comparison is the nearest qualified technician driving today's fixed truck stock.

Cost a call adds the drive and repair minutes at $1 a minute to the chance of a second visit times $165. Both dollar figures are made up, and the threshold table names every made-up value.

Jobs the truck covers is the share of jobs whose every needed part was on the truck that day, under the balanced truck. It is compared with today's fixed stock, and each comes with its cost a truck-day.

Customer's words read right is how often Claude's reading of the customer's own words matches the problem code the booking recorded. It is compared with keyword rules, the way a booking screen matches words to codes today.

The charts

Where repeat visits come from counts, per 100 jobs of each appliance, the repeat visits caused by a part missing from the truck. Its table adds the share of each appliance's repeat visits that a missing part caused. The rest failed on the technician's success rate.

Which parts to carry plots, for carry lists of 1 to 8 parts, the share of held-back jobs whose every needed part was on the list. The horizontal line is today's trucks, which carry far more than eight parts. The list's job is to top the truck up for the day, not to replace it.

What to load tonight ranks each way of loading a truck by its cost a truck-day: repeat visits for jobs the truck could not cover, parts moved on or off overnight, and the cost of money tied up in stock. Lower is better. Each bar's label also gives the share of jobs covered.

Who takes the call replays every held-back day under each way of handing out calls, with the same made-up sick calls, breakdowns and priority changes. The bar is calls fixed on the first visit; the label adds the cost a call.

Reading the customer's words compares Claude, keyword rules and a control in which Claude's answers are shuffled between bookings. The label adds how often the 3-part carry list built from that reading covered the job.

Back-orders to chase first lists each part the centers cannot ship, with the calls expected to need it before it arrives, how many of those have no truck nearby holding one, and the dollars at risk.

Every label and status, and what to do about it

How to read the computed columns

How the data is handled

Everything is invented by one seeded generator (seed 2026) and written to one SQLite file on the machine that runs it. The same seed writes the same rows every time, so every figure reproduces exactly. No real company, customer, part number or technician appears anywhere.

The report and both manuals are static pages. They load nothing from the network: no fonts, no scripts, no tracking. The published copy is the same file, built on the author's machine and checked against a fresh build before it is committed.

The AI step's answers were produced once by claude-haiku-5-5 and ship in the repository, so a run needs no key and sends nothing anywhere. Only python run.py --live calls the Claude API, with the reader's own key, and it sends the made-up booking words and problem labels and nothing else.

Every threshold, and what sets it

Read from the code at build time, so this table cannot disagree with what ran. "Made up" means a stand-in to replace with a real figure before any real decision.

What Staple cannot tell you

• Whether the gains hold on real history. The history is invented, so every figure shows the method working, not the size of a real gain.
• Real costs. The repeat-visit, handling, holding and minute costs are stand-ins. The ranking of loads can change with real costs; the break-even figure in the run says where.
• Quantities. A truck that holds a part is taken to hold enough of it. Two calls on one route needing the same part are not modeled.
• Routes. Drive time is zone to zone on a grid, not road routing, and the night plan places calls one at a time rather than solving the whole day at once.
• Why a repair failed when the parts were there. The history records the technician's success rate, not wrong diagnoses or customer no-shows.
• Whether the AI reads real customers this well. The customer phrasings are a small invented set, and the simulated customer answers the follow-up question with the booked problem.

The methods manual lists each of these corners with the upgrade that would remove it.

Glossary

back-order

A part the distribution centers cannot ship until a set day.

booked code

The problem code the booking recorded from the customer's words. Real history knows only this code.

carry list

The parts a booked call is likeliest to need, ranked by the predictor. Its length is how many parts are on it.

certified technician

A technician allowed to carry and fit locked parts.

control

A deliberately broken copy of a method with its data's links shuffled. If it scores as well, the gain is not real.

coverage

The share of jobs whose every needed part was on the list or the truck. One missing part fails the whole job.

current way

The comparison on the plan: the nearest qualified technician, driving today's fixed truck stock.

first-visit chance

The plan's chance a call is fixed on the first visit: the chance its truck holds every part the call needs, times the technician's success rate on that appliance.

first-visit fix

A repair finished on the technician's first visit: every part on the truck, and a repair that takes.

follow-up question

The one question Claude asks when it is less than 70% sure of the problem, with a few answers for the customer to pick from. Made once by the model and saved.

held-back days

The last 92 days of history. Methods learn from the days before and are scored on these.

holding cost

The yearly cost of money tied up in truck stock: 25% of its value (made up).

lean

Where a model family has little history, its odds lean on the wider group, as if 20 more jobs were seen there.

load sheet

One truck's list for the parts room tonight: each part to put on, take off or keep, with its worth and the booked calls behind it.

locked part

A part that may ride only on a certified technician's truck.

regret insertion

Placing first the call that loses most if its best technician's day fills up, not the call booked first.

repeat visit

A second truck roll because the first visit did not fix the job, costed at $165 (made up).

rolled call

A call no technician's day had room for. It moves to tomorrow and counts as not fixed today.

truck-day

One technician's truck on one day: its load, its jobs and its costs.

true problem

What was really wrong. Known here only because the history is invented.

unplanned call

A call added or moved on the day, 15% of calls (made up). No night-before list saw it.

worth

What a part is worth carrying tomorrow: each booked call's chance of needing it times a $165 repeat visit, plus a share for unplanned calls, less its holding cost. A $2 move counts against it when it is not aboard, and for it when it is.

Running it yourself

Python 3 is the only requirement; no packages are installed. From a copy of the repository:

python run.py          # builds the made-up world, every result, the metric tables and these pages into out/
python check.py        # every check, each with a control that proves it can fail
python run.py --live   # the AI step asked afresh, with your own ANTHROPIC_API_KEY

Open out/index.html in a browser. The nine metric queries are plain SQL files in sql/metrics/; each runs on its own against out/staple.db.