Usability/flow defects pass every gate: proposal for a Stage-3 interaction-model deliverable and gate #291

Summary

Three apps built with this toolkit (TramiusECI, TramiusSCR, TramiusSVC) shipped usability and flow defects that every gate passed: gate-check Stage 3/4 PASS, page-fidelity ≥80% on the affected pages, lint 0 errors, e2e 69/69. All of them were designed in at Stage 3 (wireframes, route table, nav decision) and then built faithfully. The toolkit's quality loop measures build matches wireframe; nothing measures wireframe matches how people work with 2+ objects and 2+ roles.

Proposal: a Stage-3 interaction model deliverable before any wireframe (role → home, inboxes, object hubs, navigation map, page-parameter contract, list/tabs rule, read-only rendering and field kinds per role), a two-objects-two-roles walk before the Stage-3 ✋, and a cheap model-side gate at Stage 5. Owned by a skill, enforced by the process.

Related, not duplicates: #232 (LOOK never happens during the build; its point 4 "seed two open records" is moved upstream here), #188 (UI look is advisory). Those fix Stage 5; this is about Stage 3.

Full retro with every citation: TramiusECI/docs/analysis/ux-process-retro-2026-10-13.md (commit a67a9491). Toolkit checkout used: 1d5a55c.

What went wrong — defects with evidence

D1. ECI: every stage page shows "the current change", not the one you opened

• ./mxcli -p App.mpr -c "describe microflow ChangeIntelligence.GET_Change_Current":

  retrieve $Change from ChangeIntelligence.Change
    where ChangeStatus != ChangeIntelligence.ChangeStatus.Closed
    sort by ChangeNumber asc
    first;
  

• show references to ChangeIntelligence.GET_Change_Current → 12 references, 8 pages use it as the root data view (BoardReview_Overview, BoardRun_View, Change_NewEdit, Change_Overview, ChatSession_View, ComplianceOption_Overview, ImpactGraph_View, SBCompliance_Overview). None of them has a page parameter. Same pattern 3 more times (GET_SignalCluster_Current, GET_OptionAssumptions_Current, GET_Scenario_Current).
• The stepper snippet takes $Change, but its 8 clickable tiles call show page <StagePage> with no argument (mdlsource/6-ci/81-ci-clickable-stepper.mdl) — a stepper for change B opens change A.
• Introduced in ECI 14b20e86 (day 2). Flagged by the user on day 4 (build-plan row U1). Script 78-ci-board-tasks-list.mdl then declined the real fix: "Giving BoardReview_Overview a Change page parameter would break every show page BoardReview_Overview caller (scripts 66, 69, 72, 76, 77, 81 and ACT_Change_OpenLateStage)". Still open on day 9. The cost of a Stage-3 choice compounds with every script.

D2. ECI: clicking a change "opens Signals"

describe microflow ChangeIntelligence.ACT_Change_OpenStage: at stage SignalsInbox → show page ChangeIntelligence.SignalCluster_Overview; (no parameter; grid = all signals). Later stages open the paramless pages of D1. There is no object page for a change.

D3. ECI: navigation is the process; no role homes, no inbox

• describe navigation Responsive: menu = Changes, Signals, Board tasks, Demo data, Part search, Workflow (3 of 6 are stages). home page ChangeIntelligence.Change_Overview for all 6 roles.
• The build plan (§7 "Demo users and navigation wiring") said reviewers land on #/board, admin on #/demo-data — not built; nothing compares plan homes with model homes.
• The BRD (F009) says "Reviewer opens BoardReview_NewEdit from the task inbox". Plan row 41.3 "task inbox for the 4 reviewer roles" is claimed built. No wireframe draws an inbox.
• The only navigation question asked at Stage 3 was layout: PROJECT.md "Navigation layout: top bar — CONFIRMED". A follow-up row CONFIRMED "top bar with … stage navigation" on recommendation in an unattended night run.
• All 13 Stage-3 wireframes (ECI 040f01fe) are drawn as C. Manager · ChangeManager with one change (CHG-4521) — including the reviewer's own task page. 13/13 carry "Board tasks" in the top bar.

D4. All apps: 2–5 stacked full grids on ~15 pages

From the wireframes. Fixed in the wireframes 2026-10-13 (ECI f914cc5e, 74c8b247; SCR e60aba0). SVC Fleet_Overview was wireframed with tabs (6bb6d6d) and the first build wrote in a script comment "the operator tabs are an Operator column with a text filter (a tab per OperatorAccount is not MDL-expressible)". page-fidelity scored it 49%, classes 9/26 and nothing stopped it.

D5. SVC WorkOrder_Task: read-only fields as grey disabled inputs

The wireframe marks 5 rows Read-only: yes but not how read-only renders. First fidelity score 60% (5/22 classes). Fixed today with dataview-level ReadOnlyStyle: Text (no per-widget ReadOnlyStyle in mxcli 0.25/0.26).

D6. SCR MitigationPlan_Edit: edit a cell → page reloads and jumps to the top; Owner is free text

Every cell's OnChange → ACT_PlanLine_Save → ACT_Plan_Reopen = close page; show page SupplyRisk.MitigationPlan_Edit(Plan = $Plan);. MitigationLine.LineOwner: String(100); the Stage-3 wireframe (20915a2) binding row says "Comment, Owner | Text box in grid column". Fidelity 92%, 12/12 — the best-scoring page carried two usability defects. (Being fixed by another session.)

D7. Random sign-outs (related, not concluded)

Under investigation; the trial runtime stopping itself after a random 2–4 h is one candidate. Listed so it is not mistaken for a design defect.

What was green while these existed

Root cause

1. No Stage-3 artifact owns the interaction model. Runbook Stage 3 asks for role model, boundaries, branding, nav layout, wireframes per screen, cross-persona swimlanes (who acts). Nobody is asked where each role starts, how it finds its work, what object each page is about and who passes it. ui-preflight-pages.md even notes "a navigation menu item cannot pass a page parameter" — so putting stages in the menu forces paramless pages.
2. Wireframes are drawn as one persona with one object. Every downstream check inherits that single-object, single-role world (fidelity, LOOK, journeys, seeds).
3. The per-page loop cannot see cross-page structure. module-review.md rubric row 8 already says the menu "belongs to no page, so a page-by-page review never reaches it". Homes, inboxes and the parameter contract are the same kind of thing.
4. Signals that existed did not block (fidelity < 80%, plan §7 homes vs model homes).
5. Late fixes are expensive, so known defects survive: D1 was known on day 4 and blocked by its own dependents.

Good flow currently depends on luck at Stage 3: SCR and SVC did get role homes and inboxes (SCR home page SupplierRadar for Buyer, ChangeNotices_Overview for Engineering, Supplier_Home for Supplier, menu "Approval inbox"; SVC Operator_Home and Technician_MyWorkOrders) because their wireframes happened to draw them. ECI's did not.

What went well

• Fixes landed fast once seen: tabs rework in all three apps in one day; SVC closed 9 cleanup items the same day.
• Wireframe-first gave one place to fix: the ECI nav rework (design/wireframes/NAV-REVIEW-2026-10-13.md, 74c8b247) fixed D1–D3 in the design first — a Change_Detail hub with parameter = Change, an inbox home with tabs (Waiting for you / All active / New signals / Closed), crumbs Changes / CHG / Stage, a Page parameter: Change row per wireframe. That is the missing Stage-3 artifact, produced by hand after the fact.
• BRD grounding held: the inbox was in F009; journeys cite requirement ids. The gap is BRD → screen, not the BRDs.
• Instruments did flag 2 of 6 (fidelity 49% / 60%; SVC Stage 5 FAIL). The data exists; it is not wired to stop anything.
• Model queries made verification cheap: every claim above came from describe / show references in one session.

Proposal

Skill or process? Process, with a skill as its owner

A skill already exists for each symptom, and each arrived after the defect. A page builder never reaches "which role lands where"; it builds the page it is given. The toolkit's pattern for must-happen work is artifact + gate (wireframes per screen, coverage ledger, closing rows). This belongs in that class.

1. Stage-3 artifact design/interaction-model.md (skill skills/interaction-model.md), after the role model is CONFIRMED and before the first wireframe

1. Role → home: every role names its home and what it comes to do. Default: its inbox or main object list.
2. Inboxes: every BRD user task / approval → which role, which inbox page, grouping, what a row opens (task page with its object).
3. Object hubs: every object users follow over time gets a detail hub that takes it as parameter; process steps are reached from the hub, never top-level.
4. Navigation map: menu items are object lists, inboxes or tools — never a process stage. One navigation per concept (stepper on the hub or menu, not both).
5. Page-parameter contract: page → object → parameter → opened by. Every page about one object takes that object. A parameterless "current X / first" retrieve as a page's root is not allowed (named singletons such as settings excepted).
6. Lists: one main grid per page; sibling sets in tabs with counts.
7. Fields per role: read-only per role and how it renders (text, not disabled inputs); which fields are people (user reference), dates, money.
8. Write behaviour: inline edits keep the user's place; what refreshes after a save.

Wireframe Bindings blocks gain Page parameter:, Reached from:, Drawn as role: rows.

2. Walk before the Stage-3 ✋: two objects, two roles

Walk the prototype with 2+ open objects and 2+ roles: as each role, from its home, find the work for object #2 and complete one step. Record the routes in the artifact. Stage-5 fixtures and journeys inherit it (2+ open objects, one journey per non-primary role starting at its home).

3. Gates (facts only; judgement stays in the skill)

• gate-check.sh <p> 3: artifact present; every role has a home row; every BRD user task has an inbox row; every wireframe has a Page parameter: row. The nav question to the user becomes "who lands where and how do they find their work", not only "top bar or sidebar".
• Stage 5 (gate-check or lint), from the model:
  • homes per role (describe navigation) vs the artifact;
  • pages whose root data view is a parameterless microflow retrieving … first from a non-singleton entity;
  • show page P with no argument where P takes an object per the artifact;
  • menu items whose target is a stage per the artifact;
  • page-fidelity below target blocks the next script for that page unless a deviation is recorded.

Acceptance criteria

1. skills/interaction-model.md exists and is routed in bin/lib/skill-routing.tsv for Stage 3 (architect, ba); design-artifacts.md Step 3 requires it before the first wireframe.
2. Runbook Stage 3 "Agent produces" and "Gate" name the artifact and the two-objects-two-roles walk.
3. The wireframe template carries Page parameter, Reached from, Drawn as role.
4. gate-check.sh <p> 3 fails when the artifact is missing, a role has no home, or a BRD user task has no inbox.
5. A model-side check reports homes vs artifact, "current/first" root data views, show page without a required object, and stage menu items. Against TramiusECI at 74c8b247 it reports ≥8 current-object pages, 1 home page for 6 roles, 3 stage menu items.
6. testing-shape.md / journey seeds: 2+ open objects and 2+ roles per module; one journey per non-primary role starting at its home.
7. The list/tabs rule (one main grid, siblings in tabs with counts) is referenced from the artifact and design-artifacts.md.

Info-only issue: no PR or branch attached.