The docs/specs/learning-hub/navigation.md spec is marked SHIPPED P0–P6. That happened on 3 July. P6 was site-wide Pagefind search — full-text, across the entire property, built mockup-first off scratchpad/learning-search-mockup.html and shipped on feat/learning-nav-p6-search. The navigation plan, which had been open since before the hub launched, is now closed.
The observation I didn’t write in the devlog that day: the phase that did the most navigational work wasn’t the last one.
The plan, in brief
The spec ran seven items, P0 through P6. P0 was the hub itself. P2 was the first visible post-hub change — track sections and S1 JSON-LD structured data, shipped on feat/learning-nav-p2-tracks. First run through the full UI gate since hub v1: interactive approval mockup, then code. P4 was the in-chapter TOC, the “on this page” right rail, built around a live IntersectionObserver scroll-spy off scratchpad/learning-toc-mockup.html, shipped on feat/learning-nav-p4-toc, closing N2. P5 was the prerequisite chips, closing N1 — the “Read first ↳” label at each chapter head, shipped on feat/learning-nav-p5-prereqs. P6 was search.
The M/E/N/S backlog in conventions.md carried N1’s entry as “the single highest-value navigability fix” before any of these phases shipped. That was spec analysis, not observed behaviour. Improving on the earlier treatment of that claim: P6 is now the comparison point that justifies or refutes it. It justifies it.
What P5 built
N1 is three words, a right-arrow, and one link. At the head of a chapter, before the prose begins: “Read first ↳” followed by a single prerequisite — the chapter a reader should have completed before this one makes sense. No recommendation rail, no similarity engine, no “you might also like.” One directed edge in the learning graph, surfaced at the moment it matters.
The implementation required editorial work the other phases didn’t. P2 was structural; P4 was UI mechanics. N1 required encoding actual knowledge about the content: which chapters have prerequisites, and what those prerequisites are. The chip is the rendered output; the prerequisite map is what had to exist first.
What P6 built
Pagefind indexes every page at build time. No server, no query service — the index ships as a static artefact. P6 wired the search UI into the site-wide layout so the box is available across the whole property, not only under /learning. Same process as P2 and P4: mockup first, UI gate, approval, then code.
The result is fast and accurate. Type a term, get ranked results, navigate to the page.
Why P5 has more leverage
Search solves a specific failure mode: a reader who knows they want something and can’t locate it. That’s a retrieval problem. Pagefind handles retrieval well.
Retrieval failure isn’t the primary navigational problem in a section organised around a sequential progression of chapters. The primary problem is orientation: a reader who doesn’t know what order to read things in, or who arrives at a chapter mid-sequence without the prerequisite context. That reader is confused before they finish the first paragraph.
Orientation failure doesn’t produce a search query. A reader who doesn’t know what they’re missing doesn’t know what to look for. Search can’t fix what it can’t be asked about.
The prerequisite chip intercepts orientation failure upstream. Before the reader starts the chapter, they see the one thing they should have read first. If they haven’t read it, they can navigate there immediately. If they have, the chip confirms they’re in the right place. Either way, orientation is settled before confusion begins.
That’s the asymmetry. Search is reactive — a reader who knows they’re lost can recover. Prerequisites are proactive — a reader who doesn’t know they’re disoriented gets redirected before the problem compounds. Proactive navigation intercepts the failure upstream; reactive navigation requires the failure to surface first.
The consequence for leverage: every reader who arrives at a chapter with a prerequisite encounters the chip. Oriented readers confirm they’re on track. Disoriented readers are redirected before they start. Neither group reaches for search, because neither group ends up in the state that makes search necessary.
What search does handle
Prerequisite chips don’t cover everything. Lateral lookup — a reader who wants to locate a specific concept without re-reading a full chapter — is a real use case. Serendipitous discovery is another: a reader arriving from an external search engine who wants to navigate inward without an obvious starting point. Those readers benefit from search in a way that prerequisites don’t address.
P6 shipped because those use cases are real and worth serving. Out of scope here: quantifying how often lateral lookup occurs in the learning section versus the rest of the property. That requires analytics the build pipeline doesn’t currently collect.
The order in the spec mattered
The spec was written with P5 before P6 for a reason the post-ship comparison confirms. Sequential content with prerequisite relationships has an orientation problem first and a retrieval problem second. Get the orientation layer right and you reduce the retrieval load. Add retrieval after orientation and you cover the residual.
Shipping in the other order — search before prerequisites — would have addressed retrieval for readers already oriented, which is a smaller set than readers arriving cold into the middle of a sequence. The harder navigational problem would have remained unsolved.
The post-ship closeout reconciled the M/E/N/S backlog against what actually shipped: per-item statuses across N1, N2, and the rest, with a living atlas giving the whole programme a navigable summary. The spec entry for N1 — “the single highest-value navigability fix” — was written in the analysis phase and left unchanged at close. Nothing across the seven shipped phases gave a reason to revise it.
The general point
Navigation phases split on a reactive/proactive axis that doesn’t always appear explicitly in a spec. Pagefind is a well-understood technology: box, query, result. Specifiable, buildable, verifiable with a short test list. Prerequisite chips require editorial judgement: which chapters have prerequisites, which prerequisite matters most when several candidates exist, how to represent the dependency without it reading as a warning label. That judgement is harder to carry through the build.
The harder phase was the higher-leverage one. When building a navigation spec, the question worth prioritising is which problems readers have before they know they have them. The interventions that address those problems sit upstream of anything reactive. They don’t appear in analytics as searches-not-submitted or sessions-that-recovered. They appear as sessions that never needed recovery.
Search shipped seventh because the chips that prevented readers from needing it shipped fifth. The spec had that right before any code was written.
