The spec called it before any code shipped. Under N1 in conventions.md: “Read first ↳ prerequisite chips at the chapter head — the single highest-value navigability fix.” That sat in the document for six phases while a right-rail TOC, hub track sections, JSON-LD structured data, and site-wide Pagefind search all shipped around it. P5 shipped last week. The ranking held.
This is the write-up of why.
The programme
The navigation work ran against docs/specs/learning-hub/navigation.md, seven phases from P0 to P6. P0 was the spec. P2 brought the first visible change: hub track sections and S1 JSON-LD structured data, the first pass through the full UI approval gate since the hub v1. P4 added the “on this page” right rail: an IntersectionObserver scroll-spy tracking the active heading as you scroll, implemented as a client island because that was the only part of the subsystem that needed live browser state. P5 placed the prerequisite chips. P6 shipped Pagefind search across the whole property, closing the spec as SHIPPED.
The backlog tracked items under four categories: M (must-have), E (enhancement), N (navigation), S (structured data). N1 was the chips. N2 was the TOC. Both shipped. The spec’s call was that N1 outweighed everything else.
What the chips do
Each chapter head now carries a row of “Read first ↳” links. They name prerequisite content in other chapters and link directly to it. If you land mid-hub on a chapter that assumes you’ve read three prior things, the chips name those things at the point of arrival. You don’t open the search bar. You don’t scan the TOC for context. You follow the chip.
That’s the mechanic. The effect it has on the reader is different from what search or a TOC achieves.
Why the TOC is not the same problem
P4’s right-rail TOC is built around an IntersectionObserver hook, a live scroll-spy, and a mockup at scratchpad/learning-toc-mockup.html that showed the real heading-tracking behaviour before any production code was written. The implementation is the subsystem’s only client island. Everything else is static. It’s the most technically involved piece of the programme.
What it solves: within-page orientation. You’re in a chapter, you want to know its shape, you scan the rail. You jump to a section. Useful for a long technical chapter with multiple subsections.
What it doesn’t solve: whether you’re ready to read this chapter at all.
A TOC assumes you’ve already decided to read the page. It helps you move through it. If you arrived on the wrong page because you don’t yet know what you don’t know, the TOC doesn’t redirect you. It makes the wrong page easier to navigate.
Why search is not the same problem either
Pagefind indexes the site at build time and ships a lightweight client-side search widget. The UX went through a scratchpad mockup at scratchpad/learning-search-mockup.html before any integration work. Site-wide search is the natural capstone for a navigation programme: a way to reach any content on the property from any page.
What it solves: retrieval when you have a term. You know the concept exists somewhere on the site, you want to find it, you type. The index gives you a result set.
What it assumes: that you have a term. A reader who doesn’t yet know they need prerequisite X doesn’t type X into the search bar, because they don’t know X is the thing they’re missing. They read a chapter, find it harder than expected, and either push through or bounce. Neither outcome serves them.
The chips solve for the bounced reader before the bounce happens.
The underlying distinction
A docs site and a learning hub have different reader models. A docs-site reader usually arrives with a query. They know what they’re trying to do and need the reference. Retrieval is the right first investment. Search, navigation rails, TOC: all serve that reader.
A learning hub reader often arrives without a query. They know what they want to learn, broadly, but they don’t know which chapter to start from, and they don’t know what prior knowledge a given chapter assumes. For that reader, the highest-impact intervention isn’t a better retrieval mechanism. It’s an explicit statement of prerequisites at the point of arrival.
The chips are that statement. They’re not sophisticated. They’re links with a label. The impact comes from two things. Placement at the chapter head, visible before the reader starts. And explicitness: naming the prerequisite rather than implying it through ordering.
Why the spec was right before the code existed
conventions.md called N1 the highest-value fix during the planning phase. That call had to come from a model of the reader, not from a comparison of implementation complexity. The chips are simpler to implement than the TOC. They’re less visible than search. On a feature-count or feature-impressiveness measure, they’d rank lower than both.
The model that produces the correct ranking asks: what is the reader actually blocked on? Not: what is the most complete set of navigation tools I can build?
A reader blocked on prerequisite ignorance is not served by search or a TOC. They are served by chips. The spec had a model of the blocked reader. That model produced the right priority order. The programme ran P2, P4, P5, P6, with the spec’s call visible throughout. When P5 shipped, the ranking didn’t need to be re-argued. It was confirmed.
The counter-intuition
The assumption this contradicts: navigability scales with feature count. More tools available to the reader (search, TOC, breadcrumbs, track sections) means easier navigation. The assumption is intuitive and wrong in a learning context.
P4 and P6 are both useful. The programme was right to ship them. But if I’d been forced to close the spec at one phase, the correct choice was P5. Not P6, the most feature-complete answer. Not P4, the most technically involved answer. P5, because it answered the question the reader was actually blocked on.
The lesson isn’t that chips are always the right choice. The lesson is that the prioritisation model matters more than the feature catalogue. “What is the reader blocked on?” is a different question from “what are the standard navigability features for a site like this?” The first question produces an ordering. The second produces a list. Ordered correctly, the list puts the chips first.
Close-out
The navigation spec is closed: SHIPPED P0–P6. The conventions.md M/E/N/S backlog carries per-item statuses across M1, E2, and the rest. The programme has a living atlas as a navigable artefact outside the spec document.
Out of scope: the Pagefind build-time indexing specifics, the IntersectionObserver implementation details, and the JSON-LD schema from P2. Those are in the devlog.
The next navigability question for the hub goes through the same model: what is the reader blocked on, as a specific question, before feature selection. If the answer is “they don’t know what they don’t know,” the chips are probably in the answer again.
