Approved · executed (schema v0.4)

Flow-Walk UI Prototyping Refactor

2026-06-26 · product-design pipeline · author: brainstorm session · locked decisions: compliant re-cut + extend design-tree-loop §2 · naming: prototype→logic-wiring, create-ui-experiment→build-ui-screens, new key-moments, keep consolidate-prototypes

A flow-driven, minimum-UI build mechanic for the product-design tree: build each screen in element-batches ordered by user discovery, stop when the flow is satisfied, branch per UX variation, and park-or-prune. This page captures the compliant re-cut — the version verified against the real convention, schema, and tests — and shows what is new, extended, additive, and deliberately dropped.

Contents
  1. Locked decisions
  2. The design tree
  3. Screen build loop
  4. Change set
  5. Dropped from literal vision
  6. Plumbing & verification

1 · Locked decisions

  • Shape: compliant re-cut — stay within the fixed 6-skill route tuple, node-type table, and three-role model. No route insertion, no role reclassification.
  • Batch mechanic: extend design-tree-loop-convention.md §2 to cover ordered/dependent per-unit intermediates. No standalone convention, no new generator/registry plumbing.
  • Proof ordering: a new key-moments skill on the trunk, running before state-model and ux-variations — it needs only the flow map, ranks flows by proof priority (value × risk × frequency), orders the branches, and gates variation breadth.
  • Data-first, just-in-time: state-model attaches per promoted flow only — modeled when key-moments promotes a flow to build, never for pruned flows. UX variations re-skin the data layer; later flows extend the core model rather than re-derive it.
  • Progressive fidelity: split the builder into build-ui-screens (visual wireframe in element-batches) → logic-wiring (clickable, state-backed; keeps prototype's CLI/API/infra modes).
  • Selection & widen: /uat --variant-evaluation picks the canonical screen per flow, then two-stage /consolidate-prototypes stitches canonical screens → cohesive flows → full prototype. Off-ramp = additive parked / cherry_pick_candidate.

2 · The design tree (the hourglass)

route node (unchanged) new skill renamed / extended data substrate (state-model) consolidation (widen) pruned / off-ramp
topic root design tree user-flow-map enumerate ALL flows — structure only key-moments NEW — rank flows by proof priority orders branches · gates variation breadth for each promoted flow, in priority order — just-in-time state-model gate attach data substrate for THIS flow (JIT) ux-variations fan out up to N — re-skin the model variation · parked soft-stop → cherry-pick variation · selected descends into builder chain variation · pruned dropped ui-interview screen packet + batch plan build-ui-screens visual wireframe · element-batches logic-wiring clickable · state-backed · CLI/API/infra approved screen canonical leaf uat --variant-evaluation compare clickable variations → pick canonical / variation widen back up — consolidate-prototypes (two-stage) stage 1 · stitch approved canonical screens → cohesive user-flows + cherry-pick parked variations stage 2 · assemble flows → full cohesive prototype → AFPS graduation
Scope narrows descending the trunk, then widens back up through consolidation. user-flow-map enumerates every flow; key-moments (new, on the trunk) ranks them by proof priority and gates variation breadth; then, just-in-time per promoted flow, the state-model gate attaches the data substrate before ux-variations fans out branches that re-skin it. The selected variation descends the builder chain — ui-interview → build-ui-screens (visual wireframe) → logic-wiring (clickable, state-backed; keeps CLI/API/infra) → an approved canonical screen. uat picks the canonical screen per flow; parked variations stay available to cherry-pick. Consolidation then widens in two stages: stitch canonical screens into cohesive flows, then assemble flows into a full prototype for AFPS graduation. State-model and data are built just-in-time per promoted flow — pruned flows are never modeled.

3 · Screen build loop — progressive-fidelity ladder

build-ui-screens — visual batch loop target = action/state matrix user-flow-map order = discovery sequence progressive_review visual batch N add UI for flow-step N visual checkpoint review vs matrix minimum UI? no → next batch (add more elements) yes "don't like where this goes" logic-wiring — clickable, state-backed wire → state-model wireframe → clickable flow reachability acceptance check binding gate one per variation off-ramp: park parked + cherry_pick_candidate retained, not pruned
A progressive-fidelity ladder. Top band — build-ui-screens runs the visual batch loop: each batch adds only the elements needed to make the next flow-step reachable, a light visual checkpoint reviews it against the action/state matrix, and the loop halts at minimum UI. Bottom band — once visual is satisfied, logic-wiring upgrades the wireframe to a clickable, state-backed contained experiment wired to the flow's state-model, then a flow-reachability acceptance check feeds exactly one binding alignment gate per variation. The red off-ramp parks a stalled build (parked + cherry_pick_candidate) without pruning, so it stays available to cherry-pick.

4 · Change set

ElementKindDetail
key-moments skillnewTrunk skill, runs before state-model/ux-variations (needs only the flow map). Ranks proof order (value × risk × frequency); writes existing journey_sequence / evaluation_priority / branch_order_override / priority_rationale. Orders branches and gates variation breadth. Both mirrors at v0.0.
state-modelextendData-first, just-in-time: attaches per promoted flow only (after key-moments promotes it), never for pruned flows. Later flows extend the core model rather than re-derive it.
prototype → logic-wiringrenameRenamed and scoped to logic: upgrades the wireframe to a clickable, state-backed contained experiment, validates flow reachability. Keeps prototype's non-UI runnable modes (CLI / API / infra = "runnable logic"). Updates the route-tuple const + tests + handoff strings; schema_version v0.3 → v0.4.
create-ui-experiment → build-ui-screensrenameRenamed and scoped to the visual wireframe builder: runs the element-batch loop with a visual checkpoint per batch and a minimum-UI stop rule. Feeds logic-wiring.
design-tree-loop §2extendAdd ordered/dependent per-unit intermediates (batches). Defines batch = one flow-step, minimum-UI stop rule, moment-level end-to-end acceptance. Regenerate via existing upgrade-design-tree-loop.mjs.
ui-interviewextendAdditionally authors the batch plan in its packet. Role unchanged — not an orchestrator.
consolidate-prototypes (two-stage)extendAdd stage 1 (stitch approved canonical screens → cohesive user-flows) before the existing stage 2 (assemble flows → full prototype → AFPS graduation).
flow-tree.schema → v0.4additiveOptional fields only: build_ledger[] on ui_experiment; parked enum value + cherry_pick_candidate boolean. Plus route-tuple rename prototype → logic-wiring. Sample stays valid.
Comparison / selectionreuse/uat --variant-evaluation picks canonical per flow → two-stage /consolidate-prototypes; parked branches feed cherry-pick.

5 · Dropped from the literal vision

These were verified to collide with load-bearing invariants (fixed route tuple, node-type table, three-role model, filesystem-existence cursor) and were cut to stay drop-in compliant.

droppedui-interview as orchestrator directing build-ui-screensViolates the three-role model. Replaced by: ui-interview authors the plan, executor builds.
droppedscreen-orchestrator skill + screen nodeNo screen node exists; route insertion breaks the const tuple + tests. Deferred; add screens[]/screen_id as optional schema only if later proven necessary.
droppedVariation-level comparison gateWhole-unit review already covers a branch's variations; built comparison lives in UAT.
droppedFour-level resume cursorViolates "cursor = filesystem existence." Variation + batch map onto the two existing cursor levels.

6 · Plumbing & verification

Schema & tests

  • Bump schema_version v0.3 → v0.4; update the const assertion in tests/layer1/product-design-flow-tree.test.ts.
  • Any extended enum is asserted as an exact array — update it.
  • Keep every new field optional so flow-tree-sample.yaml stays valid.
  • Expect SKILL.md prose assertions to shift with routing/wording edits.

Skills, mirrors & build

  • Behavioral edits → skill-archive.sh + version bump + CHANGELOG, in both claude + codex mirrors (parity-audited).
  • key-moments: author both mirrors, PACK.md line, required_conventions, add to convention Sets, run generators, git add bundles.
  • Convention edit → rerun upgrade-design-tree-loop.mjs; commit regenerated DESIGN-TREE-LOOP.md.
  • Stage-before-build, then regenerate manifest + both showcase data files; run build:check + validate:data.
Status: APPROVED & EXECUTED (2026-06-26) — the flow-walk re-cut shipped against flow-tree schema v0.4. Naming convention (locked): prototype → logic-wiring, create-ui-experiment → build-ui-screens, new key-moments, keep consolidate-prototypes. Deprecated prototype and create-ui-experiment aliases still route to the primaries. This supersedes the older state-model-first proposal (docs/proposals/state-model-first-pipeline-refactor.md), cherry-picking only its state-model fast-pass fold and per-screen model_ref.
Deferred (separate pass): standardizing on "experiment" as the single word for a contained build would mean a schema-wide rename — prototype_build_plan/prototype_build_item/prototype_build_status/prototype_path → experiment_* and node status promoted-to-prototype → promoted-to-experiment — with its own schema_version bump and test/handoff updates. Out of scope for this refactor to avoid a half-rename that splits "experiment" (skill name) from "prototype" (schema vocab).