Take a topic through the screen pipeline

Table of Contents

This page documents a runbook — a named, repeatable composition of recipes and skills for a complete multi-step procedure. Each step references a recipe or skill by id-link.

1. Goal

Take one topic of Screen pipeline topics from the person's goal to a signed off screen, so that every screen of the web speaks the one UX language and the next topic repeats the same steps without discussion. Each step ends in a document a person signs off: the journeys, the prototype, the screens, the scenario and the sheet. The calendars topic ran it first, in Take the first reference data topic through the screen pipeline, and this page is what that run taught.

2. Preconditions

3. Steps

In execution order. Each step is one task of the topic's story, worked through Work a task through to merged PR; a step that ends in the owner's sign off leaves its task STARTED and waiting on them until they have spoken, and closes on the next PR.

  1. Extract and judge the journeys. Start from the person's goal, not from the Qt dialog. Read the topic's row and the matrix; find the journeys that exist under User Journeys and write the ones that do not, with compass add user_journey as New user journey says. Then judge each step of each journey on the journey page, under Screens and wireframes, in a table of step, shape on the screen, and judgement: a step the standard record screen already draws, a kind's own action by RS-PAGE-03, a view no rule draws yet, a missing server operation, or a step that keeps state across a reply and so needs a workflow under the Workflows menu. Add the * Prototype section the journey contract requires, link each gap in What is missing to its capture, and name the placements the prototype must decide. Stop for the owner: the journeys are signed off before any prototype. Record the sign off and its decisions on the journey, the task and the story's * Decisions.
  2. Prototype the screens. One prototype per topic under doc/prototypes/<group>/<name>/, as the Prototypes page requires: plain HTML, CSS and JavaScript, the web app's tokens, the query string as the state so every screen, dialog and reader view has an address a reviewer opens. Draw the screens where the standard settles them and nowhere else; where no rule covers a part, define it in the design note for the standard to take. Copy no history, dialog or panel from a live screen or an older prototype without checking it against the standard: the live reference data screens still carry the legacy HistoryPanel, and the first calendars prototype copied it (see the memory History is the shared timeline, never the compare panel). The design note cites the rule identifiers each screen follows, lists every state's address and says what is fake; the group page and the top page list the prototype; the journey's * Prototype section links it. Render every state with Playwright and read the screenshots against the checklist before the owner does. Stop for the owner: the prototype is signed off before any code; their corrections are PRs on the same task.
  3. Build the screens. Move the live screen to the prototype, and land each move in the shared part the standard names, so that no screen builds a dialog of its own and every record screen gains the fix: RecordHeader, RecordDialog, PartsPanel, RecordDetails, RecordTimeline, RecordList. A kind's own action that answers in one reply is an operation dialog opened from the header. The strings exist in English, French and Portuguese before the screen ships. Where the harness has no check for a rule the build relies on, add one to projects/ores.web/packages/harness/tests, titled by the identifier, so the legacy shape cannot pass a sign off again. Prove the build on the running web with the harness on the screen alone and a scripted drive of the editable path; the dialog checks skip on a screen whose first row is read only, so derive or add a record to reach them.
  4. Test and sign off. Follow How do I test a feature after implementation?: recreate the database and provision Acme as How do I ready up an environment? says, write the test scenario with compass add test_scenario over list, page, create, amend with a stale version, parts, derived views, history and revert, delete, and the reader, and drive it with a script kept in the task's evidence/ folder, one function per step, until every failure is the screen's and not the script's. Press Refresh after every write in the script and in the words, because the page does not reload by itself. Then follow How do I sign off a screen?: the harness on the screen alone, the sheet from screen_sign_off.py, the person's lines filled from the scenario and its screenshots, the verdict. File every gap as a capture or fix it when it is the screen's and small; a gap the owner's run finds in the standard changes the standard, with the date and the reason on the rule. Stop for the owner: they run the scenario by hand and walk the sheet; their verdict is the sign off that closes the topic. Record it on the scenario, the sheet, the task and the story.
  5. Close the topic. Close the story with its decisions distilled, and scaffold the next topic's story from this runbook with the same four tasks, in the order of Screen pipeline topics. The close PR of each topic adds what the topic taught to the section below, under the topic's name and date, so the page grows without being rewritten.

4. Postconditions

  • The topic's journeys carry a judgement per step and the owner's sign off.
  • The prototype is on main under doc/prototypes/<group>/, listed and signed off, with the rule it added to the standard recorded there.
  • The live screens draw what the prototype draws, through the shared parts, in three languages, with a harness check for every rule the build relied on; the harness on each screen has no failure that is the screen's.
  • The scenario is PASSED by the owner's own run, the sheet carries their verdict, and every gap found is a capture or a fix.
  • The story is DONE with its decisions, and the next topic's story exists.

5. What the topics taught

5.1. Calendars, 2026-10-25

  • The topic's journey already existed; the task was to judge it, not to write a second one. Look before writing.
  • A copied screen copies its legacy. The first prototype carried the two-pane history compare from the live currencies page and the classifications prototype; the owner caught it. The timeline is the only history.
  • The owner's run of the scenario changed the standard twice: a record's history carries its parts (RS-HIST-01), and the tabs a read-only kind lacks stay hidden. Expect the standard to move at the sign off and write the decision on the rule.
  • The scenario script's first failures were its own: it looked for a row before pressing Refresh, clicked the header's Edit instead of the row's, and left a regex literal uninterpolated. Three runs found two server gaps along the way: a deleted calendar's days stay behind, and a re-created key continues the old history.
  • The harness skips the dialog checks on a screen whose first row is read only; derive or add a record to reach them, and let the scenario create and delete its own.
  • The local gate can be red on main's defects while the branch is clean; prove whose failure it is on a clean worktree of origin/main and capture it rather than wait.

6. See also

Emacs 29.3 (Org mode 9.6.15)