DEV Community: Todd Sullivan

The AI-Generated Word Document Opened. Its Numbering Was Broken.

Todd Sullivan — Tue, 03 Nov 2026 09:05:54 +0000

I used four specialised AI agents to turn 41 messy handover documents into four usable artifacts: two spreadsheets, a summary, and a 17-process training checklist.

The agents finished. The files existed. The row counts were right. The document opened.

Then I looked at the checklist.

Every numbered step continued from the previous section. Process 2 started where process 1 ended, and the document eventually ran from 1 to 169. The content was mostly fine. The structure underneath it was not.

A .docx is a ZIP of OOXML files, so I inspected word/document.xml instead of trying another prompt:

import zipfile

with zipfile.ZipFile("Process Checklists.docx") as docx:
    xml = docx.read("word/document.xml").decode()

print(xml.count("<w:numPr>"))
# 0

The generated paragraphs used Word's shared ListNumber style, but none had an explicit numbering reference. The file was valid enough to open, while still being semantically wrong. Word treated the steps as one long list.

I rebuilt the document generator so every list that needed to restart received its own w:num instance, and every numbered paragraph received an explicit w:numPr reference.

The verification was deliberately structural:

paragraphs with explicit numPr: 318
distinct list instances used: 58
numbering instances declared: 67
orphan references: 0

I also replaced the flat heading hierarchy and emoji warnings with real heading styles, consistent callout blocks, page headers, footers, and restrained typography. That part was visual. The numbering bug was not; it needed an OOXML check.

The useful lesson was not “AI is bad at Word documents.” The agents did the expensive content work: cataloguing 41 files, building 17 procedures, and identifying nine gaps where the source notes were incomplete.

The failure was in the acceptance test. I had checked that the artifact existed and contained text. I had not checked that Word interpreted the document structure correctly.

For AI-generated office files, my minimum gate is now:

verify the expected content and counts
inspect the package structure for references and relationships
render or open the artifact to check layout
test the failure-prone feature directly

A generated file is not done because it opens. It is done when the application consuming it behaves correctly.

I Used 25 Simulated Players to Verify an AI-Assisted Swift Refactor

Todd Sullivan — Tue, 27 Oct 2026 09:08:37 +0000

I let Claude co-author a fairly invasive refactor: split an adaptive iOS game's reusable AI engine out of the app repository and consume it as a versioned Swift package.

The change touched 47 files. The app commit removed 2,664 lines and added 112.

A clean build was not enough evidence that this worked.

The engine contains the parts that influence behaviour: telemetry, player modelling, the adaptive Director, difficulty guardrails, rendering support and persistence. The app keeps its own level rules, scoring, upgrades and room templates. A dependency can compile while a moved default, changed data boundary or subtly different seed path changes how the AI behaves.

So the architecture rule was:

reusable policy and infrastructure go into the engine package
game-specific rules stay in a local StationRules package
game-specific room data stays in the app
the app pins the engine at 0.1.0

Then I used the headless simulator as a behavioural checksum.

I built and ran the same deterministic 25-player simulation immediately before and after the split. Both runs produced exactly:

levels completed: 237
run overs: 1
boss attempts: 317
boss wins: 239 (75%)
rooms: 1,987
deaths: 61
shot accuracy: 0.490
labels: 2,410 total — 191 bored, 2,171 flow, 36 frustrated, 12 aboutToQuit

The numbers matched exactly.

All eight StationRules tests passed too, but those tests only cover isolated scoring, upgrades and progression rules. The simulator crosses the useful boundary: generated rooms, bot behaviour, combat, telemetry, adaptive decisions and engagement labels all running together.

That matters more when an AI coding agent is doing the refactor. Agents are good at moving symbols, fixing imports and making the compiler green. They are less able to prove that a stateful adaptive system still behaves the same after ownership moves across packages.

The useful pattern was not “review every changed line harder.” It was:

make the simulation deterministic
capture a small set of behaviour-level outputs
perform the architecture change
require exact output equality

That turns a large AI-assisted refactor into a boring comparison.

For deterministic systems, a behavioural checksum is often a better refactor test than another pile of mocks. The compiler proved the package boundary was valid. The simulator proved I had not changed the game hiding behind it.

The AI Coding Agent Passed the Build. The App Still Crashed on Launch

Todd Sullivan — Sat, 24 Oct 2026 12:22:40 +0000

I had Claude co-author an adaptive audio feature for a small Swift game.

The code compiled. The tests passed. The app installed. Then it crashed as soon as the audio engine called its render block.

There was no useful exception message, just SIGTRAP.

The problem was where the closure had been created. The audio class was @MainActor, so Swift 6 treated the render closure as main-actor isolated too:

let node = AVAudioSourceNode(format: format) { _, _, frames, buffers in
    synth.render(frames: Int(frames), into: buffers)
    return noErr
}

That closure does not run on the main actor. Core Audio calls it from a real-time audio thread. The compiler accepted the handoff, but the runtime actor check trapped the first time Core Audio invoked it.

The fix was small: form the callback outside the actor-isolated context and make the threading contract explicit.

nonisolated private static func sourceNode(
    format: AVAudioFormat,
    synth: MusicSynth
) -> AVAudioSourceNode {
    AVAudioSourceNode(format: format) { @Sendable _, _, frames, buffers in
        synth.render(frames: Int(frames), into: buffers)
        return noErr
    }
}

The more useful fix was to the workflow.

I had treated a clean build as evidence that the agent-written change worked. It was only evidence that the types lined up. The failure lived at a runtime boundary: framework callback, different thread, stricter Swift 6 isolation.

Now any AI-assisted change that hands a closure to a system framework gets a tiny runtime gate:

launch the app in the simulator
exercise the callback path
leave it running for 60 seconds
only then install or ship the build

This is not an argument against coding agents. Claude helped diagnose and fix the crash as well. It is an argument for testing the boundary the compiler cannot prove.

AI-generated code is especially good at looking locally correct. Framework callbacks fail globally: actor isolation, lifecycle, permissions, background execution, hardware state.

The lazy guardrail is not another review checklist. It is one runnable smoke test that crosses the real boundary.

My AI Model Was 89% Accurate. It Missed 99% of the State I Cared About

Todd Sullivan — Tue, 20 Oct 2026 08:07:34 +0000

I trained a small CoreML classifier to estimate whether a player was bored, in flow, frustrated, or about to quit.

The training pipeline looked respectable:

headless game simulator
bots with randomised aim, dodging, recklessness and patience
deterministic seeds
player-level train/test split
class-weighted loss
132,139 labelled rows across 2,400 simulated players

The test accuracy was 89.4%.

Then I looked at the classes instead of the headline number:

bored          recall 95.5%
flow           recall 94.8%
frustrated     recall 98.2%
aboutToQuit    recall  1.1%

The model was almost completely missing the state I cared about most.

There was another problem hiding underneath it. While watching the simulator, I found bots freezing in cleared rooms. The navigation was fine. The bot's stuck recovery was not.

Every 30 frames it checked whether it had moved. If not, it sidestepped for 40 frames:

if clock % 30 == 0, distance(pos, lastPos) < 0.5 {
    detour = 40
}

A sidestep into a wall was still active at the next check, so it could trigger another sidestep and loop forever. I had generated plausible-looking training rows from an agent that was sometimes just stuck.

The fix was tiny: make the detour shorter than the check interval and alternate sides.

if clock % 30 == 0, distance(pos, lastPos) < 0.5 {
    detour = 20
    detourSide = -detourSide
}

I also added a simulator invariant: if a bot stays in a cleared room for more than 60 seconds, count it as a stall and fail the data run. The original issue appeared in 75 of 450 sessions. After the fix, the detector found zero stalls across 2,400 simulated players.

Clean data did not magically fix the rare class. Overall accuracy stayed at 89.4%, while aboutToQuit recall actually fell from 15.4% to 1.1%.

That was the useful result.

The simulator bug and the label problem were separate failures. Fixing corrupt behaviour made the dataset honest; it did not make the label learnable. The rare state still overlaps heavily with frustration and needs better labels or real player data, not another round of metric tuning.

My rule now is:

simulators need behavioural invariants, not just successful exits
splits must be by actor, not by row
every important class gets its own metric
low-confidence model output falls back to deterministic rules

An AI pipeline can be reproducible, testable and 89% accurate while still failing its actual job.

The CoreML Model Was Fine. The Photo Was Too Big.

Todd Sullivan — Tue, 13 Oct 2026 08:03:32 +0000

I hit a very ordinary computer-vision failure this week: the model was doing what I asked, but the image pipeline was making the task impossible.

The app counts livestock on-device with a small YOLO/CoreML model. No network, no account, no server-side fallback. That constraint is useful, but it means the phone pipeline has to be honest about what the model actually sees.

The first photo path looked sensible:

let request = VNCoreMLRequest(model: model)
request.imageCropAndScaleOption = .scaleFit
handler.perform([request])

One image in, detections out.

Then I tested it on a real paddock photo with roughly 250 sheep in it. The count came back as 14.

That was not a model mystery. A 12MP photo was being squeezed into the model input. By the time the flock reached the network, distant sheep were just a few pixels each. There was nothing clever for the detector to recover.

The fix was boring and much better than changing the model:

run the full image once
run overlapping tiles over the same image
map tile-relative boxes back into image coordinates
drop boxes cut by an inner tile edge
merge the remaining detections with class-agnostic NMS

The important bit is that tiling changes the object size the model sees without changing the model.

let regions = [CGRect(x: 0, y: 0, width: 1, height: 1)]
    + Self.tiles(aspect: aspect, across: 3, overlap: 0.25)

for region in regions {
    request.regionOfInterest = region
}

On a 4:3 photo that becomes 12 tiles plus the full-frame pass. More inference, but still on-device and still only a fraction of a second for a still photo.

The same paddock photo went from 14 to 173 detections. Not perfect, but suddenly useful. Close-up hen photos held steady, which mattered just as much: the fix improved recall where scale was the problem without inflating easy counts.

The non-obvious part was the merge step.

Default IoU-only NMS is not enough when tiling. A partial head box can sit inside a whole-animal box and have low IoU, so I also merge on intersection-over-smaller. I also make the merge class-agnostic because the same animal can come back under two labels from different passes. Count the animal, not the label argument.

The lesson was simple: before blaming the model, check what pixels you actually gave it.

For on-device AI, the model is often the least flexible part of the system. The image pipeline around it is where the cheap wins hide.

My AI Cron Job Failed Because .env Wasn't a Shell Script

Todd Sullivan — Tue, 06 Oct 2026 08:03:11 +0000

I hit a small failure in an AI publishing cron job this morning that is exactly the kind of boring edge that makes agents unreliable.

The job needed one secret:

DEVTO_API_KEY=...

The lazy version was to source the whole env file and let the shell export everything.

set -a
. ~/.hermes/.env
set +a

That is fine until the env file stops being a shell script.

This one had unrelated values in it. One contained an app path with spaces. Another looked enough like shell syntax to be treated as a command. The job still found the API key later, but the logs had the real problem:

Chrome.app/Contents/MacOS/Google: No such file or directory
fyqi: command not found

Nothing about the Dev.to API was broken. The agent had just widened the trust boundary for no reason.

The fix was not to make the env parser clever. It was to stop parsing the file as code.

import re
from pathlib import Path

text = Path.home().joinpath(".hermes/.env").read_text(errors="ignore")
match = re.search(r"^DEVTO_API_KEY=(.*)$", text, re.M)
api_key = match.group(1).strip().strip('"\'')

That is deliberately boring. It reads exactly the value the job needs and ignores everything else.

The useful rule for agent jobs is:

if a task needs one credential, load one credential.

Do not source a shared env file just because it is convenient. AI agents already have enough ways to do surprising things. Giving a scheduled job a file full of executable shell lines is a cheap way to add another one.

This is especially true for personal agent infrastructure, where the same .env tends to collect API keys, browser paths, tunnel tokens, feature flags, old experiments, and comments that were never meant to be interpreted by sh.

The failure mode is annoying rather than dramatic, which is why it is worth fixing. The job does not need a config framework. It just needs to stop executing config.

Small boundary. Small parser. Fewer weird mornings.

The 8B Local Model Was Worse Than the 4B One

Todd Sullivan — Tue, 29 Sep 2026 08:02:49 +0000

I tried the obvious local-LLM upgrade on a small Mac mini: move from a 4B model to an 8B model.

It was worse.

The machine is an 8GB Apple Silicon mini running a personal assistant stack. The useful path was already working with mlx-community/Qwen3-4B-4bit through Swama's OpenAI-compatible endpoint:

4B weights: ~2.3GB
warm plain reply: ~1s
warm tool-call round: ~3-4s model time
full tool response: ~7-18s, depending on external APIs

So I pulled the 8B quantized model to see if the extra capability was worth it.

The first trivial request was enough:

8B weights: ~4.3GB
"say hello": 14s
throughput: 6.8 tok/s
swap churn: ~1.6GB in/out
free memory: basically zero

That was not an edge case. That was the cheapest possible prompt.

A real assistant request is heavier: system prompt, recent conversation, tool schemas, maybe a tool round, then a final answer. If the 8B model swaps on hello, it is not going to survive a weather/tool/home-status request while the rest of the app is running.

The annoying part is that the model choice looked sensible on paper. 8B should be smarter. It probably is, in isolation. But local AI work is not model leaderboard work. It is memory pressure, cold starts, prompt prefill, tool reliability, and whether the box is still usable after the request.

The fix was not glamorous:

MAX_HISTORY_MESSAGES = 10

@lru_cache(maxsize=1)
def get_ai_handler():
    return SwamaAIHandler()

Cap the prompt history. Reuse the handler. Keep long-term memory as distilled facts, not raw transcript replay. Use the 4B model that stays resident and answers quickly enough.

I also had to add boring production guardrails:

run the real Swama binary, not the symlink, because first inference crashed loading MLX's metallib
keep the model warm because idle eviction made cold starts painful
strip <think> blocks from streamed responses because /no_think was not enough after tool calls
bias the prompt toward tool use for live data, because small models will confidently answer from stale weights if you let them

The lesson was simple: on tiny local hardware, the best model is the one that leaves enough machine behind for the product.

The 4B model shipped. The 8B model got deleted.

The AI Coding Agent Wasn't the Risk. The Missing Deploy Gate Was.

Todd Sullivan — Tue, 22 Sep 2026 08:03:37 +0000

I had a small reminder this week that AI-assisted development does not really change the old rule: if a human or an agent can edit a deployment path, the deployment path needs to prove the important thing still works.

The bug was not dramatic. A routing service sits behind a tiny Caddy gate because the upstream server has no auth of its own. Requests without ?key= should get 403; requests with a valid key should route.

That was already checked after deploy:

check 403 "without key" "https://$FQDN/route?$ROUTE"
check 200 "with key"    "https://$FQDN/route?$ROUTE&key=$KEY"

Good enough for the live app. Not good enough for App Review.

The app also needs a separate review key. A reviewer opening a fresh install cannot use a key already typed into my own devices. So Caddy accepts two values for the same query param:

@authorized query key=LIVE_KEY key=REVIEW_KEY

The failure mode was easy to miss: a deploy could ship a Caddyfile that still accepted the live key but silently dropped the review key. The health check would pass. The app would still work for me. Then days later App Review would open the build, hit the first-run screen, and reject it.

That is the worst kind of infrastructure bug: green deploy, delayed failure, wrong human paying the cost.

The fix was nine lines:

# The key issued to Apple's Beta App Review, when this machine holds one.
# Absent file, no review key in play, nothing to check.
if [ -f .secret-review ]; then
  check 200 "review key" \
    "https://$FQDN/route?$ROUTE&key=$(cat .secret-review)" || ok=1
fi

No framework. No secret-management migration. Just make the deploy assert every key path that matters.

Claude co-authored this change, which is the bit that made it worth writing down. Not because the agent did something dangerous. Because agent-written code has the same problem as human-written code, only faster: it can make a local patch that looks right while missing the operational contract around it.

The useful pattern is simple:

let the agent edit the boring deployment code
make the deploy script test the real external behaviour
fail before the broken state becomes somebody else's problem

For anything with AI in the development loop, I care less about whether the diff looks plausible and more about whether the system can prove the side effect survived.

In this case the proof is three HTTP codes:

without key -> 403
with key    -> 200
review key  -> 200

That is not a big security architecture. It is just a tripwire in the place I am guaranteed to step before shipping.

The On-Device People Counter Only Worked After I Made It Boring

Todd Sullivan — Tue, 15 Sep 2026 08:02:58 +0000

I built a tiny line-crossing people counter for a Seeed XIAO ESP32S3 Sense this week. Camera on the board, model on the board, counts on the board. No laptop in the loop unless I want the more accurate host-mode version.

The first useful constraint was admitting what the hardware could actually do.

The host detector runs at 416×416 and is about 1.1 GFLOPs. That is fine on a laptop. On an ESP32-S3 it is fantasy. The on-device detector is roughly 15× smaller and still takes about 118 ms per frame.

At QVGA the budget ended up like this:

JPEG decode      ~30 ms
preprocess        9 ms
model           118 ms
postprocess       2 ms
---------------------
total          ~160 ms

So the real target is not “real time” in the desktop-CV sense. It is about 6 fps, which is enough for someone walking through a doorway if the rest of the pipeline does not get clever.

The counter is deliberately plain:

capture the newest frame
detect people
use the bottom-center of each box as the foot point
match points with a nearest-centroid tracker
count when a track crosses a configured line
log the event to serial, optionally expose /counts over WiFi

The foot point mattered more than I expected. Box centroids move around with posture and crop shape. If the counting line is on the floor, the bottom-center of the box is a better approximation of the thing that actually crosses the line.

The tracker is also intentionally boring:

// ponytail: no motion model, no re-id. Fine for a doorway at ~6 fps;
// swap in ByteTrack if people cross paths in frame.
class Tracker {
  // id -> centroid, max distance, max age
};

No Kalman filter. No re-identification. No cloud fallback. Just keep a track alive for a few missed frames and drop it when it gets too stale.

That is not because those techniques are bad. It is because this is a doorway counter on a microcontroller. People mostly move in one direction, the camera points down, and the useful failure mode is obvious: if people cross paths in frame, this tracker is too small and should be replaced.

That shape is easier to operate than a “smart” pipeline pretending it has more signal than it does.

The board can serve its own tiny monitoring page when WiFi is configured:

GET /counts
{"in":14,"out":11,"occupancy":3}

But it also works serial-only with empty WiFi settings. That was another good constraint. The core counting path should not depend on a dashboard, a backend, or a phone app being alive.

The bit I like most is that the counting logic has a host self-check separate from the ESP-IDF build:

make -C firmware/test
# ok: 6 counter tests

For edge AI, that split is worth doing. The model and camera are the annoying parts to test. The line-crossing rules do not need to be. Pull the state machine into boring C++, beat it up on the host, then let the board worry about frames and inference.

The lesson was the same one on-device AI keeps teaching me: the model is only one budget. Latency, memory, camera format, mounting angle, testability, and failure honesty matter just as much.

A smaller model plus a boring counter beats an impressive pipeline that cannot keep up with someone walking through a door.

The Credit Counter Race That Let 50 AI Requests Through

Todd Sullivan — Tue, 08 Sep 2026 08:03:40 +0000

I fixed a boring little backend bug this week that would have been expensive in exactly the way AI features like to be expensive: quietly, under concurrency, while every individual request looked valid.

The app has Claude-backed generation behind a monthly credit allowance. Simple shape:

authenticate the user
check their subscription and monthly allowance
call Claude
record the generation and token cost
increment credits_used

That looks fine until you remember the model call is the slow part.

The old gate read credits_used, saw the user was under the cap, then let the request continue. Only after the multi-second Claude call did it increment the counter.

So a user sitting at 29 / 30 credits could fire 50 parallel requests. All 50 read 29. All 50 passed the gate. All 50 spent tokens. Then the counter landed at 79.

No exotic attack. No clever prompt injection. Just check-then-act around a slow side effect.

The fix was to stop treating the credit check as application logic and make Postgres do the one thing it is very good at: serialize writes to the row.

create or replace function public.reserve_ai_credit(
  p_user_id uuid,
  p_month text,
  p_limit integer
) returns integer language plpgsql security definer as $$
declare
  v_used integer;
begin
  insert into public.ai_usage (user_id, month, credits_used)
  values (p_user_id, p_month, 1)
  on conflict (user_id, month) do update
    set credits_used = ai_usage.credits_used + 1
    where ai_usage.credits_used < p_limit
  returning credits_used into v_used;

  return v_used;
end;
$$;

That where ai_usage.credits_used < p_limit on the conflict update is the whole trick. Concurrent requests now queue on the same row. The first one increments. The next sees the updated value. Once the cap is reached, returning gives nothing back and the request stops before the model call.

The Edge Function now reserves a credit before calling Claude:

const { data: used, error } = await supabase.rpc("reserve_ai_credit", {
  p_user_id: user.id,
  p_month: month,
  p_limit: allowance,
});

if (used === null || used === undefined) {
  return json({ error: "Credit limit reached" }, 429);
}

That changes the failure shape, so the other half of the fix was refunds. If the model call fails, or the structured response violates the schema, the function calls refund_ai_credit. Failed generations should not bill the user, but they also should not leave the gate open until after the expensive work is done.

While I was in there, I removed a duplicate credit gate from one function and made it call the shared runCreditGate path like the others. That cut about 52 lines and made the concurrency fix apply everywhere instead of only to the function I happened to be staring at.

A few adjacent bugs fell out of the same pass:

uncapped text fields could push huge strings into prompts
avgSleepHours.toFixed() could throw when the client sent a string
an unknown Claude model name logged cost as $0 silently
one suggestion endpoint was returning 401 for “no subscription”, which signs the user out instead of showing the paywall

None of those needed a grand framework. Just input clamps at the boundary, one shared gate, and loud logs when accounting metadata drifts.

The useful lesson: if an AI feature has a quota, the quota has to be enforced before the model call, in the database, atomically. Anything else is a polite suggestion with a cloud bill attached.

I ran the Supabase Edge Function helper tests after the fix: 62 Deno tests, 0 failed.

The Tracking Bug Wasn't the Model. It Was the Dot Lying.

Todd Sullivan — Tue, 01 Sep 2026 08:07:11 +0000

I spent part of this week debugging an on-device livestock counter in a field-video mode. The model was fine. The count was not.

The symptom from the real device run was simple: a tracking dot would leave one animal, drift onto its neighbour for a few frames, then snap back. In a dense mob that is exactly the kind of tiny lie that ruins the user's trust. If the UI says that sheep is being tracked, it had better mean it.

The first version of the counter was deliberately boring:

detect animals with a small CoreML model
maintain short-lived tracks between frames
count when a track crosses a tripwire line
let missed tracks coast for a few frames so one bad detection does not drop the animal

That worked in still-ish tests. It failed once the phone and the sheep were both moving.

Prediction is not presentation

The lazy assumption was that the predicted track position could also be the drawn dot position.

Bad assumption.

A tracker is allowed to guess. A UI marker is a claim. Those are different contracts.

A track can go unseen for up to 15 frames, because dropping it too quickly loses animals behind brief occlusion. During that time prediction uses the last observed heading plus camera-motion compensation. Good for matching. Bad for display. On a slow pan, a neighbouring sheep is about one body length away, so a few frames of coasting was enough to draw the dot onto the wrong animal.

The fix was smaller than the bug report made it sound:

let visibleCoastLimit = 2
let isDisplayPrediction = track.missedFrames > 0

if track.missedFrames <= visibleCoastLimit {
    drawDot(at: track.predictedCenter,
            opacity: isDisplayPrediction ? 0.45 : 1.0,
            scale: isDisplayPrediction ? 0.7 : 1.0)
}

Matching can keep the longer memory. Display gets the honest one.

Centroid distance breaks in a flock

The second bug was association cost.

I had already moved past purely greedy matching, but the cost was still mostly centroid distance. That sounds reasonable until you put the phone in front of a packed group of sheep. Every animal has another animal a body length away. Centroids are not enough signal.

The better signal is overlap.

Two boxes on the same animal overlap heavily between adjacent frames. Two boxes on neighbouring animals usually do not. So the association cost now prefers overlap first and only falls back to distance when there is no meaningful overlap:

if iou > 0 {
    cost = 1 - iou
} else {
    cost = 1 + normalisedDistance
}

That one change makes the tracker much less willing to jump to a neighbour just because its centre is nearby. It also means tracks need to keep the whole observed box, not just a centre point and longest side. Slightly more state, much better truth.

The useful lesson

Most ML product bugs are not model bugs.

The detector can be good enough and the product can still feel broken because the tracking layer lies, the UI overstates certainty, or the recovery path optimizes for the wrong thing.

In this case the fix was not a new model, a heavier tracker, or a dependency. It was separating prediction from presentation, then using the geometry the video already had.

Boring, local, testable. My favourite kind of AI fix.

Development Notes: Navigation UX Is a State Problem

Todd Sullivan — Mon, 31 Aug 2026 17:21:46 +0000

Recent FlatNav development has been a useful reminder that navigation UX is mostly a state-management problem pretending to be a design problem.

The visible part is the map, route, buttons, and labels.

The real work is deciding what the user needs to know right now, what can wait, and what should never be shown at all.

Good navigation software has to stay calm while the user is not. That means the interface needs to handle uncertainty without pushing it onto the person using it.

The useful questions are simple:

what state is the journey in?
what is the next useful action?
has the user changed context?
does the UI need to interrupt, confirm, or stay quiet?
is this information actionable now, or just noise?

Most improvements come from reducing interpretation.

If the user has to stop and decode the screen, the app has already leaked complexity. If a feature adds more choices than it removes, it probably made the system feel smarter while making the user slower.

That is why the best development cycles often look small from the outside: clearer states, fewer edge-case dead ends, tighter feedback after actions, better defaults, less UI competing with the next step.

There is a lazy engineering lesson in that.

Before adding another control, another setting, or another explanation, ask whether the state model is doing its job. Often the fix is not more interface. It is making the existing state clearer, deleting an unnecessary decision, or moving logic into the product so the user does not have to carry it.

Navigation products get better when they get quieter.