The /docs mashup that broke the IA

The message arrived on a Tuesday morning, 2026-05-05, in a working channel that was not meant for product feedback. It was eleven words long.

I can't find /docs from /ship.

It came from inside the team. That is part of why we trust it. The sender was not stress-testing the site or running a survey — they were trying to do a thing, on the site they had helped build, and the thing was not findable. The honest version of the moment is that the message sat for a few minutes before anyone, including the recipient, took it seriously. It looked cosmetic. Someone moved a link, someone else will find it, this is the kind of thing we fix on Friday with a one-line nav patch.

It was not that.

The two-second read

The two-second read is that a colleague got lost in the header. The header is a flat strip of links — /ship, /lighthouse, /docs, /blog, /about — and from inside /ship the /docs link was still there, in the same place it had always been, doing the same thing it had always done. The complaint, on its face, was that the navigation pattern was not clear enough. You can fix that with a tooltip, a section label, an underline, a breadcrumb. None of those would have helped.

The reason none of those would have helped is that the user was not asking where the link was. They were asking what would happen if they clicked it.

The thirty-second read

/docs was a hub. We had folded the Ship reference and the Lighthouse reference under one URL when there was very little of either, and the consolidation had aged into a problem. By the time the message arrived, that hub was carrying a mashup: half of it described an SDLC orchestrator with policies and a tracker, the other half described an evaluation harness with prompts and a grader. A user reading from /ship clicked /docs and met a Lighthouse concept on the first scroll. A user reading from /lighthouse clicked /docs and met a Ship concept on the first scroll. The complaint was not "I can't find the link." The complaint was "I clicked the link and the page does not know who I am."

The two-second read is cosmetic. The thirty-second read is architectural. We almost shipped the cosmetic fix.

The diagnosis

One hub. Two products. Two readers. No shell discipline.

The hub had been a packaging convenience when both product surfaces were thin. It worked until each product grew enough reference material that the hub had to choose, on every page, whose vocabulary to use. Workspaces or eval runs. Policies or graders. Tickets or prompts. There is no neutral wording for those choices. The page that tries to serve both audiences ends up serving neither, because every section forces a context switch and every nav rail competes with the one above it. The /docs hub had become the site's single most expensive page to read.

The other half of the diagnosis is that the nav shell — the strip across the top, the rail down the left — was the same on every URL. You could be deep inside a Ship adapter reference and the left rail would still offer you Lighthouse grader examples three clicks down. That is not a navigation problem you can solve with a label. It is a problem that says the shell does not know which house you are in.

The fix

Per-product nav shells. /ship/docs and /lighthouse/docs each own their reference, with a nav rail that only talks about one product. /docs becomes a thin disambiguation page — two cards, one sentence each, a choice. Everything that used to live under /docs/... got a 308 at the old URL pointing to its new home. The redirect discipline is the one we wrote down last week in no broken links, second time — same rules, same map, same CI guard refusing to merge a route change that leaves an old URL stranded.

The engineering work was straightforward. Move files. Add 308s. Split the shell component into two. Update internal links. The hard part was the decision to do any of it, because at every step the cheaper version of the fix was still on the table. "Just add a section header." "Just colour the links." "Just put a tab strip on /docs." None of those would have answered the actual complaint. All of them would have left the next confused user with the same problem in a nicer wrapper.

Eight person-days, end to end. Most of that was reading every old URL and deciding which new house it belonged in. The redirect table is sixty-three rows long. The 308s are in production. The disambiguation page is two cards. The first user to follow the same path our colleague followed now lands on /ship/docs and reads a Ship sentence on the first scroll. The shell knows which house you are in.

How to tell which is which

The wider lesson is the one we keep relearning, and the reason this post exists.

A cosmetic complaint says this is hard to use. The button is small, the link is hidden, the label is unclear, the page is slow. Cosmetic complaints cost you a UX tweak. They are real, they deserve fixing, and the fix is local — the rest of the site does not move when you fix one.

An architectural complaint says I don't understand the model. I clicked the thing that named what I wanted and I got something that named a different audience. I read the page that said it was for me and it was for someone else. I followed the nav and the nav stopped matching the URL. Architectural complaints cost you a refactor. The fix is never local, because the thing that is wrong is the relationship between pages, not any one page.

The test we are starting to use, after this one: if the complaint can be fixed by changing pixels, it is cosmetic. If the complaint requires moving content between URLs, it is architectural. "I can't find /docs from /ship" reads as a pixel complaint and is in fact a content-location complaint. The signal is in what would have to change to satisfy the user, not in how the user phrased the problem.

That signal is easy to miss because users do not file bugs in the system's vocabulary. They file bugs in their own. They will say "I can't find X" when the real problem is that X has two meanings and they were handed the wrong one. They will say "the page is confusing" when the real problem is that the page is being asked to seat two readers on one bench. Translating from their words to the architecture is our job, and it is the job we almost skipped on May 5.

Who gets to file these

The other reason this post exists. We took the message seriously because we knew the sender and the sender knew the system. That is fair, and it is also a problem. A confused stranger filing the same complaint, in the same eleven words, would have gone in the bin behind a cosmetic fix. The architecture would still be wrong; we just would not have heard about it from someone whose voice we recognised.

We are not going to solve that with a form. The thing we can do — the thing this autopsy is for — is build a habit of reading short complaints twice. The first read tells you what is hard to do. The second read tells you what model the user was holding when they tried to do it. If the two readings disagree, the complaint is architectural, and the cosmetic fix is a trap.

Architectural complaints are gifts. They are slow to write, easy to misfile, and almost always come from someone who cared enough to stay confused long enough to type the message. We were lucky we listened to this one. The next one is somewhere in a working channel today, eleven words long, looking like it can wait until Friday.

It probably cannot.