# Onboarding gaps What a reader with no context could not work out from this repository, and what they worked out wrongly. This is the critique log of the Handoff stage, and it is the stage's entry order: every row here is either closed by a Handoff artefact or is refused out loud with a reason. **It was not written by imagining a newcomer.** Whoever built this product cannot read it, only recall it: every "unclear" has an answer in their head that is on no page. So the reading was done by a subagent with a clean context, on 2026-08-23, and the two lists below are its own. --- ## How the reading was produced **The order.** Get oriented (what is this, which folder is the product, what is the entry point, what is the system, where do strings live, which theme is primary, is there code), then prepare to build ONE screen that does not exist yet. Read-only: nothing in the repository was created, edited or deleted, and the working tree was clean before and after. **The three rules the prompt carried, each as an explicit line.** 1. **Read from disk.** A file already sitting in context is a snapshot taken earlier and is not a source. Without this line an agent reports on text the file no longer holds, and does it confidently. 2. **Forbidden paths, named one by one, not as a class.** "No critique logs" does not work, because the logs sit inside folders the agent was just handed. Named: `wireframes/_critique.md`, `ui-kit/docs/audit.md`, `ui-kit/docs/census.md`, `ui-kit/docs/consistency.md`, `ui-kit/docs/consolidation.md`, `docs/kit-archive/`, `concept/old/`, `ui-visual/old/`, `handoff/`, and any Critique / Defect section inside `research/`, `ia/`, `voice/`. 3. **A reading journal**: every file opened, in the order it was opened. The journal is the proof of isolation, and it is checked against the forbidden list. A hit voids the run; it does not discount it. **Isolation held.** 56 journal entries, 0 forbidden reads. Two near-misses were disclosed by the agent rather than found: a listing of `ui-kit/docs/` showed the four forbidden filenames with no content, and a `find` over `.impeccable/` printed critique filenames. `.impeccable/` is a critique log that Rule 2 did not name, which is the rule proving itself: a class-level ban leaks and a path list does not. Neither file was opened. **One environment finding, recorded here because it changes how the next reader measures.** The Playwright MCP in this session refuses `file://` outright. This repository's whole method rests on reading pages from disk, because `file://` gives every document its own opaque origin and that is what makes the icon sprite a script and the fonts and trust art `data:` URIs. The agent had to serve the tree over `http://127.0.0.1`, which is the one protocol the doctrine says is not sufficient on its own. A disk reading needs the global `playwright@1.62.0` driver directly, not this MCP. **Roll-call.** The agent returned **12** rows in LIST A and **93** in LIST B. Every row below is verified: **12 of 12** and **93 of 93**, none dropped, none merged. **One input the pack expects and this repository does not have.** Half of this step is normally already done, by the Rollout stage's "subagent questions" section. There was no Rollout stage here: the tree was painted at UI + Visual (stage 08) and every stage after it kept the tree in step, so `ui-kit/docs/rollout.md` does not exist and there is no pre-taken set of reader questions. The whole of step 1 therefore stands on the single run above. Said out loud rather than compensated for. --- ## LIST A - could not work out Verified line by line against the disk on 2026-08-23. Four verdicts, and the fourth is the one that becomes a written decision rather than a document: - **ABSENT** - the answer genuinely is not in the repository - **ELSEWHERE** - it is there, in a place the reader had no reason to look - **MISSED** - it is there, where they were looking, and they did not see it - **DELIBERATE** - it is a decision that was taken, and it is written down nowhere | # | Question | Verdict | What the disk says | Closed by | |---|---|---|---|---| | A1 | Is there a procedure for adding a SCREEN, the way there is for a component and a pattern? | **ABSENT** | `ui-kit/docs/architecture.md` has fifteen numbered sections. §11 is "How to add a component", §12 "How to add a pattern", §13 "Where a change goes". There is no section for a screen, and the procedure really is spread over six files. | `one-shot.md`, step 7 - it is exactly the missing §11.5, written as a prompt | | A2 | When I add a screen, who updates the navigation panel in the other documents, and how? | **DELIBERATE** | Correct that no registry covers the screen trees and that the scripts that held them were deleted with all 63 generators. The rule that answers it ("a sweep is a throwaway script") is in root `CLAUDE.md` and does not name this job. See B72: the reader also got the shape of the panels wrong, which makes this the most expensive unwritten thing in the repository. | `behaviour.md` is not the place; this goes to `one-shot.md` "file and registration" and to `docs/backlog.md` as the registry debt | | A3 | `ia/docs/blocks.md` banks exactly one page type. What do I do for a type it has not banked? | **ABSENT** (the method), **present** (the rule) | `blocks.md` has one type section, "Type 1: the static content page", plus "The four rules a row obeys". The four rules are the method's contract; the two-source procedure (competitor crawl + Refero by page type) exists only as one worked instance and is nowhere stated as mandatory or optional. | `one-shot.md` names the four rules as the gate and refuses to invent the rest; the banking method is a `docs/backlog.md` row | | A4 | What is actually open in `docs/backlog.md`? | **MISSED**, and the file earned it | The header does say "**Open: 0**, counted from the rows below on 2026-08-21" - dated, computed, correct. Measured now: **234 rows, 234 struck, 0 open.** But it is buried under four consecutive paragraphs of superseded self-counts (45, 47, 44, 0, 2), each correcting the last, in a 518 KB file. A dated true number that reads as one more correction is a number nobody can spend. | `handoff.html`, "what was deliberately not done", routes to the backlog with the count computed on the day | | A5 | Does a new screen family need a page in `ia/annotations/`? | **DELIBERATE** | 15 annotation pages against 15 screen families; search, the four static documents and the system pages have none, and the generator that built them is gone. Nothing states whether the folder is frozen, incomplete or optional. It is frozen in practice and that has never been written. | A decision entry in `docs/decisions.md`, plus one line in `handoff.html`'s route | | A6 | Which metadata does a new indexed page get, and must it exist before the page is built? | **ELSEWHERE** | `ia/docs/pages/seo.md` has six numbered page-family sections plus a global footer section and the A-E template. A seventh type has no section. The ordering question (A-E before or after the build) is genuinely unanswered; `terms.html` is the only precedent and it went both ways. | `behaviour.md` source column, and the ordering goes to the NOT DECIDED list for the owner | | A7 | What domain does the product live at? | **DELIBERATE, and already written** | `{ROOT}` is `[?]` by a stated decision with its cost written beside it (`seo.md` line 30): no canonical and no `og:url` can be written without it. The README's GitHub Pages links use `predict-market`, which is neither the folder name nor the product name Yonder - that half is unverified and is a real README defect. | `handoff.html` "who decides after handoff"; the README links are checked by the route instrument at step 5 | | A8 | Is there any test, lint or CI? | **ABSENT by decision, and the decision is loud** | No `package.json`, no `.github/`, no `Makefile` - verified. "0 gates, 0 generators, no build step" is stated in three files with the seven days and 145 MB it cost. What is genuinely unexplained is `venv/` and `pw/`, two Python virtualenvs sitting untracked inside the folder with nothing naming either. | `handoff.html` PACKAGE BOUNDARY; the two venvs get one line in the route | | A9 | Who owns product decisions after handoff? | **DELIBERATE** | `PRODUCT.md` says "Solo: product, design and development" and names counsel as the decider for jurisdiction, "the one open item in this file whose owner is not in this repository". Everything else is unattributed: no CODEOWNERS, no maintainer list, no contact. The answer is true and is written nowhere as governance. | `handoff.html` WHO DECIDES - a required section of the page for exactly this reason | | A10 | How many markets have fixture data, and where is the canonical list? | **ELSEWHERE, and the three numbers are three different questions** | `PRODUCT.md`: about 25 open at once, curated - the product's design target. `assets/search.js`: 27 events extracted from the tree on 2026-08-20 - a dated hand copy. `docs/launch-catalog.md`: 7 markets with a named resolver each - what release 1 opens. All three are correct and none is the canonical fixture set, which is the markup of 119 documents and exists in no data file. | `behaviour.md` names the three and which question each answers | | A11 | Where does a page script go and what may it do? | **ABSENT** | The rule for the two shared scripts is explicit and correct. The ceiling is not written anywhere: how much behaviour may live inline, whether a script may write a class the system styles (it does - `oddsbar` has 0 source placements and 72 rendered), and how a hook is registered. `Script hooks:` in a stylesheet header is the CSS half only. | `one-shot.md` and a `docs/backlog.md` row for the missing script contract | | A12 | What is `figmosha2/` and does it matter? | **DELIBERATE, and written in the one place nobody reads for this** | `.gitignore` line 7 excludes it as a nested tool repo. It is not part of the 679 tracked files. No repository document mentions it. | `handoff.html` PACKAGE BOUNDARY, which lists what is inside the folder and outside the package | --- ## LIST B - understood it as 93 confident conclusions. This is the more expensive list: "could not work out" is a known hole, and "understood it as" with a wrong conclusion is a hole no other instrument in this repository can see, because the reader was not confused, they were sure. **Roll-call: 93 = 84 correct + 1 wrong + 5 correct from a source that is stale + 3 correct and written down nowhere.** The 84 were checked against the source each row cites and stand as written; they are the reader correctly recovering the rules, and they are the evidence that most of this repository transmits. The nine that did not are below. ### The one that was wrong | # | The conclusion | Verdict | What the disk says | Closed by | |---|---|---|---|---| | B72 | "The screen-tree panel is hand-written markup inside `