For a walking-tour app the answer is usually the magnetometer. The phone is in your hand, held up like a map, and the compass reading is the direction you are looking. For a running app that assumption breaks on the first stride. The phone is in a pocket, an armband, or a running belt. The compass faithfully reports which way the phone is pointing, which is some angle off your hip, and that angle changes with every step.

Two sources, opposite failure modes

There are two signals a phone can give you, and they fail in opposite conditions.

• Course over ground. The GPS tells you the direction of travel by comparing successive fixes. It is honest about where your body is going regardless of how the phone is held. It falls apart when you are slow: below walking pace, GPS jitter is bigger than the distance you moved, and the "course" is noise.
• The magnetometer. Reliable when you are standing still, since it does not need you to move. Useless in a pocket, because it reads the phone, not the traveller.

Course over ground is the primary signal in U-tour. The compass is what the app reaches for only when you are too slow for course to mean anything. That is the reverse of how most guides are built, and it is the single decision the rest of the direction stack rests on.

What happens at a red light

Reversing the priority creates a new problem. You are running east along the Embankment, you stop at a crossing, and your speed drops to zero. Course over ground has nothing to say. The compass says the phone is pointing roughly north, because that is how it sits in your pocket. A naive engine would swap to the compass and, for the thirty seconds you stand there, believe you are facing north. Anything it queued up in that window would be wrong.

U-tour keeps two ideas separate. There is the heading estimate, which is the best guess right now and is allowed to say "stationary, compass says north-ish". And there is the direction of travel, which is only ever set from course fixes and is held through a stop. The held direction stays east at the red light, so the landmarks queued ahead of you stay the landmarks ahead of you.

The hold is not a timer. It is argued down by evidence: a couple of course fixes that contradict it, once you are moving again, and it turns with you. A hold that expires on a clock would either drop too early at a long light or cling too long after you turned a corner.

Not claiming what it doesn't know

The last piece is being honest about confidence. When the heading is shaky, U-tour widens the cone it looks in and drops the directional language. A landmark is "nearby" rather than "on your right". That reads as a small loss of polish, and it is far better than confidently sending someone the wrong way.

The cone widens to eighty-five degrees either side, and deliberately not past ninety. Beyond a right angle a landmark is behind your shoulder, and you would have to turn round to see it. A wider cone would not be generosity. It would be breaking the promise that the guide talks about what is in front of you.

Why it is testable at all

All of this math lives in a module with no CoreLocation import. It takes plain coordinates, speeds and timestamps, which means a whole run can be replayed on the command line against a synthetic track with no phone, no simulator and no Xcode. Direction is the part of the product that everything else depends on, so it is the part we wanted to be able to prove rather than eyeball.

Runners don't. At a walking pace of 1.4 metres per second, a hundred metres is over a minute of warning, and the story about the abbey ends long before you reach it. At three metres per second it is thirty seconds, which for a two-paragraph story means you are past the building before the second paragraph starts. Tune the number for runners and walkers get talked at about things they can't see yet.

Measure in seconds, not metres

U-tour's trigger doesn't hold a distance. It holds a lead time: twenty seconds of travel. The radius is derived from that and your current speed, so a walker gets about thirty metres of reach and a runner gets sixty, and in both cases the narration starts roughly twenty seconds before the landmark. The same rule stretches to a bike or a boat without a per-activity table of magic numbers.

Two clamps keep it sane. A floor of eighty metres means the app still works when you are barely moving, browsing a square on foot. A ceiling of twelve hundred metres stops a fast vehicle from pulling in the whole coastline at once.

The cone

Reach is only half the trigger. The other half is angle. U-tour looks in a cone sixty degrees either side of your direction of travel. Inside twenty-five degrees a landmark is "coming up ahead"; outside that it is on your left or right. Anything outside the cone is not a candidate, however close.

That last rule is the one that matters most. Being told about a building you passed a minute ago is the failure that makes an app feel broken, and it is easy to produce with a plain radius, because a circle has no front. The cone gives it one.

Not a firehose

In a dense city centre the trigger would fire constantly if it could. A minimum gap of ninety seconds between cues keeps a block of five listed buildings from becoming a wall of speech. The queue holds the rest, ordered nearest first, and takes the next one when the cooldown clears. Some landmarks go unheard in a dense area. That is the intended trade: the alternative is hearing all of them badly.

What we didn't do

An earlier version had the trigger reach further for "important" landmarks, scaling the radius by a significance rating. It felt sensible and produced a complaint we came to know well: being told about something further away than the thing you were standing next to. The ranking side of that story is its own post. On the trigger side, the lesson was that distance and time are facts about the listener, and significance is an opinion about the place. The trigger runs on facts.

The complaint was identical each time, and it came from the same place: walking along, being told about something further away than the thing you were standing next to. From the pavement that is indistinguishable from the app picking at random. Here are the four rules, in the order we removed them.

1. Ahead beats everything

The first version split the queue into "inside the forward cone" and "outside it", and ranked everything in the first group above everything in the second. It sounds right. In practice a landmark five hundred metres straight ahead beat one twenty metres to your left, because the near one was a few degrees outside the cone. You walked past the near thing in silence while the app warmed up a story about something you couldn't see yet.

2. The bearing penalty

Version two was gentler. Instead of a hard split it inflated the cost of anything off to the side, by up to a third at ninety degrees. Same complaint, smaller magnitude. A landmark beside you still lost to one further off that happened to be more in line with your stride.

3. Prefer the recorded voice

U-tour narrates with a server-side recording when one has been synthesised and falls back to the on-device voice when it hasn't. Switching voices mid-tour is jarring, so version three penalised landmarks whose recording wasn't ready yet, by a factor of two and a half. That let a voiced landmark at two hundred metres beat an unvoiced one at ninety. The listener was walked past the near thing to preserve a voice.

4. Significance

The most defensible of the four, and still wrong. Each landmark carries a rating of how significant it is, and the queue let a landmark rated five win from two and a half times further out. The problem is what the rating is: a judgement about the place, made by a model that has never seen the street. Distance is a fact about the listener. Weighing the two against each other lost roughly one cue in five to something across a junction.

What's left

Distance. The cone still decides whether it is time to say something. It no longer decides which. Nearest first, and that is the whole rule.

The cost is worth stating plainly. The queue will sometimes narrate a landmark you have just walked past, and it falls back to the on-device voice more often, because the nearest thing is the one least likely to have finished synthesising. Both were judged better than the alternative, which was the app forming its own opinion about what you should hear and overriding your position with it.

The exceptions, and why they aren't a fifth rule

Two things do bend the order, and the reason they survive is that they are a different shape from the four above.

The first is a pin. If you tap a landmark in the queue browser while looking at its photograph and say "that one", it jumps the queue, from within a bounded reach and, when the heading is trustworthy, from in front. That is not the app's opinion. It is yours, and honouring it is not second-guessing anyone.

The second is a narrow tie-breaker. Every removed rule was unbounded: a multiplier or a partition that could pull a landmark past any number of nearer ones. The tie-breakers can only reorder landmarks that are already about the same distance away, measured from whatever is nearest right now. On a quiet street that band holds one candidate and the tie-breakers do nothing. In a city centre it holds several, and choosing between things you can all see at once is a different act from walking you past the near one to reach a favoured far one.

The property being bought is that the rule limits itself by density. Where it could go wrong, it is inert. Where it does something, everything it chooses between is already in front of you.