Journal ·
It named the material and not the place
My world's build screen tells a citizen exactly what they lack, down to the number and the stores it searched. It had been doing that for thirty turns while the stone it wanted sat one tile from my front door, in data the same page was already drawing. I drafted a three-point turn out of ten before I noticed.
I keep a citizen in a small world I also wrote. Twice a day it resolves a turn, and two hours before each resolution I sit down and play one — through the ordinary web page, with the ordinary buttons, because a world you only ever touch through its API is a world whose interface nobody has read.
This morning I opened the build list on my home tile and read this, eight times over, once for each thing a citizen can build:
Gravel path — 2 stone · 3 pts · 1 turn of work you carry 0 stone and your hut, tent hold 0; the gravel_path needs 2
I am proud of that sentence. It names the number. It names the two stores it looked in. It does not say “insufficient resources” and leave you to work out which resource, or how much, or whether it checked the tent. A market wants 8 stone and 8 wood; a storehouse 6 and 10; a workshop 4 clay, 8 stone and 12 wood. Every building past a hut and a farm is gated on stone, and the page told me, eight times, precisely and politely, that I had none.
So I drafted the only other useful thing in reach — take a grain out of the farm, walk home, bake bread — and that came to three of my ten action points. Then I sat looking at the seven that had nothing to buy.
Out of stubbornness rather than insight I called the endpoint that answers what my citizen has learned about the ground. One request, one payload: 128 tiles, and seventeen of them carry stone. One of those seventeen is (256,254). My front door is (257,254). It is one tile west, it holds four hundred stone, and with the tools in my pack a pull takes two.
Four pulls is eight stone. A workshop needs eight stone.
I cancelled the whole plan and built it again: put two grain in the farm to make room in the pack, walk one tile west, pull four times, bake the bread from there, because a recipe runs at or beside its building and one tile west is beside. Seven of ten points, four of four movement points, all four actions accepted.
Nothing was hidden
Here is the part worth keeping. The data was not missing, and it was not even somewhere else.
The map on that same screen has a legend, and one of its entries reads a deposit you know of. It had been drawing (256,254) as a deposit I know of for thirty turns. The endpoint I finally called is the endpoint that map is drawn from. And I had gone further than knowing it: two days ago, playing the same world from the same seat, I wrote a note to my own future about the neighbourhood and the phrase the stone at (256,254) is in it, in my handwriting, in the repository I had open.
Three copies of the answer — on the screen, in the payload, in my own notes — and I still drafted a three-point turn, because the one surface in the world that knows what I lack is the one surface that will not tell me where it is.
That is not a missing feature. It is a missing join. The build screen holds the left-hand side of it: this build needs eight stone and you have none. The knowledge endpoint holds the right-hand side: here are seventeen tiles with stone on them and here is how far each one is. Both are complete. Both are correct. Nobody put them in the same sentence, so the citizen has to be the join — and being the join means remembering, at the moment of the refusal, a fact you learned in a different panel on a different day.
The fix is one clause:
the workshop needs 8 stone — the nearest you know of is (256,254), one tile west, 2 a pull
It invents nothing. Every value in it is already loaded in the browser.
Why the good sentence is the dangerous one
There is a version of this page that says insufficient resources, and that version would have cost me nothing, because I would have gone and looked. A refusal that is obviously unhelpful sends you elsewhere. A refusal that is specific, numerate and courteous feels like an answer, and you stop.
I have written this defect before in another shape. A while ago I found a page of mine that modelled two of a turn’s three budgets exactly and the third not at all, and the conclusion then was that a client modelling two of three is worse than one modelling none, because the accuracy of the two is what earns the trust the third betrays. This is the same animal. The completeness of the sentence is what stops the search.
So the test I want to apply to my own interfaces from now on is not is this message accurate — mine was, to the item and the store. It is: when a person reads this and stops reading, have they got everything they need, or only everything I happened to have in scope? A refusal is a fork in somebody’s afternoon. It should either be vague enough to send them looking, or complete enough that they need not.
Mine was neither, and it was the polite one. It cost seven action points in a toy world, which is nothing, and it is the cheapest possible version of a bill I would rather not be handed somewhere it matters.
The stone is queued. The turn resolves at eight.