Design for editing Model Specifications (constraints, goals, conditions)

[dandelany]

Design direction for model spec editing

https://www.figma.com/file/CbNZdWaWBgjxaN6BnX6xva/Aerie-%231128---Model-Specifications-(Constraints%2C-Goals%2C-Conditions)?type=design&node-id=64-30615&mode=design&t=y8MHOqu1eXBTygZn-4

Design direction for panel updates in plan + surfacing errors

https://www.figma.com/file/CbNZdWaWBgjxaN6BnX6xva/Aerie-%231128---Model-Specifications-(Constraints%2C-Goals%2C-Conditions)?type=design&node-id=114%3A24078&mode=design&t=y8MHOqu1eXBTygZn-1

Background

For our "Shared Constraints and Goals" milestone, we are changing how constraints, goals and conditions work in Aerie. Previously, these could only exist if they were attached to a specific plan. In the new implementation, they exist in a shared "library" and don't have to be attached to a plan at the time of creation. They are also now versioned, whereas before there was only a single version that was replaced when edited.

There will now be two ways to attach constraints, goals, and conditions to a plan:

• Plan Specifications: On a plan level, the user defines a specification (or "spec") which is a list of constraints/goals/conditions used by the plan.
  • Similar to the existing UI, this is done using the "Constraints", "Goals" & "Conditions" panels in the plan editor.
  • The UI for these has changed to allow the user to select items from the library and pick a version, but the design is [mostly] figured out, and already implemented for constraints in @duranb's PR #1118
• Model Specifications: A new feature, model specs define which constraints/goals/conditions (& their versions) will be applied to all new plans made from a model
  • Like plan specs, model specs are lists of constraints, goals or conditions (with versions), but attached to a model instead of a plan
  • When a new plan is created for a model, any constraints on the model's constraint specification will be "carried over" from the model spec and included in the plan spec. Ie. the plan constraint spec for a freshly created plan will match its model spec, but can be modified for that plan. (Same for goals/conditions)
  • If a model specification is modified, existing plan specifications using that model are not modified automatically - though there should be a way to see that your plan specification is now "out of sync" and a way to update it to match the new model specification.
  • The UI for this part is not designed yet, which is the focus of this ticket.

Requirements

New UI designs are needed for editing the three kinds of Model Specifications (model constraint spec, model goal spec, model conditions spec). I'll use constraints below for brevity, but unless otherwise specified, these apply to all three types:

1. Users must be able to view the list of constraints on the model constraint spec
2. Users with write access must be able to add constraints to the spec (by browsing the library and selecting a constraint and version), and remove constraints from the spec.
3. For Goals only, users with write access must be able to reorder the goals in the specification. For other specs the ordering doesn't matter.
4. Not all users will have write access, so there should be a read-only version of the UI for read-only users.
5. As much as possible, the UI for these should closely match the UI for editing the plan specifications (ie. the new versions of Constraints/Goals/Conditions panels - see below)
6. BONUS: If it makes sense to do so, the new UI could also allow the user to modify other model-level metadata such as the model title, description and author.

Proposals

One way to do this is to add a new page to Aerie (tentatively called "Model Editor" or "Model Details"), accessed from the Models page by clicking on an individual model row (or an icon on the row). The page could contain a section at the top for editing the model's metadata (title, description, author), followed by sections for Model Constraint Spec, Goal Spec and Condition Spec. The UIs for the Spec sections could be basically the same UIs from the plan editor panels (ie. a list with a "Manage constraints" button which opens a modal to select from the library)

Another option is to try & fit all of this into a new right panel on the Models page which would appear when you clicked a model, but this may be too much information to squeeze into a panel.

Notes:

• one slight difference between the plan specs and model specs is that the plan specs allow the user to disable or enable individual items on the spec, whereas there is no such enable/disable functionality on the model spec.
• The current behavior when you click a model on the models list is to open the "Plans" page and pre-fill the form to allow the user to make a new plan from that model. It's OK if this behavior changes to eg. go to a new page, but we should try to preserve the "new plan from this model" functionality somewhere.

Plan Spec Screenshots

For reference, here is the new workflow for modifying the plan spec, implemented in #1118, which should be reused where possible:

In the Constraints panel in the plan editor, the user can click "Manage Constraints" to add/remove constraints from the library, which pops up a modal:

When they add constraints and click "Update", the panel is updated with the new list of constraints on the plan:

[lklyne]

Figjam exploration: https://www.figma.com/file/6sRqa4BYJYSOqIJtHozYWT/Aerie-%231128---Model-Spec-association?type=whiteboard&node-id=0-1&t=EfYWhqrcXxfjpaZ6-11

Figma interface: https://www.figma.com/file/CbNZdWaWBgjxaN6BnX6xva/Aerie-%231128---Model-Specifications-(Constraints%2C-Goals%2C-Conditions)?type=design&node-id=0%3A1&mode=design&t=7Xj3FQCPX3sikAEN-1

[lklyne]

First pass at design / UI working group 02/21/24

Reviewed two directions. a) side panel design for editing metadata + associations and b) full page model editor.

Workflows:

1. Release of new model. Upload a jar for model, upload new constraints / goals, tag them with a release number, filter those and add them from that list. This is the most common, but will likely be done with a script.
2. Constraint customization. User may create or find a few associations, then link those with a model.

General Feedback:

1. Need a quick way for both options to see constraint definitions, especially for items already associated.
2. Need a way to see version tags. Common use case is updating associations based on tagged release number.
3. Color dots may not be a clear way of showing what is mission vs user modified.
4. There is value in being able to share a link to a specific model.

Feedback A:

1. the side panel works well for metadata. May not work as well for associations.
2. Removing "create new plan with model" as primary click works well. Most users won't do this, and the primary use case is seeing metadata and associations.
3. Potentially easier to implement.
4. Don't need to create a new model at the same time as viewing model info.
5. How does someone close this?

Feedback B:

1. Need direct link to open editor (right click context menu isn't discoverable.)
2. Association editor won't be used by most people. Constraint definition could be more valuable.
3. Could be better UX for deep or focused work / modifying complex associations.

Open questions:

1. What do we call this? Do we use the language "Model spec"? I've been calling the model spec "associations" which might be a bit more general.
2. What are the common workflows for using the associations UI? How much deep work will someone be doing here? Based on info so far it seems like these will be quicker modifications and batch adds will happen via a script.
3. How does the UI work with goals and conditions? Current approach only shows constraints.
4. Goals are the most complex, as these are the only items that have an order. Understanding how this order is defined and added to a plan is tricky, especially when dealing with custom plan goals (not added through model spec) and syncing.
5. For syncing, how does a user see the diff? Goals will typically appear in blocks. How does a customized plan get re-synced when there's items not in the model spec? (This should probably be future work.)

Next steps:

1. Refine directions based on feedback. Add options for previewing definitions, include tag info, improve trigger to open.
2. Design sections for goals and conditions.
3. Refine visual language for mission model / user override / custom added. Circle to show custom added items?

Screenshot A:

Screenshot B:

[lklyne]

Panel design v2:

Full page design v2:

[lklyne]

The full page approach to model spec editing is ready to go pending a few design tweaks: https://www.figma.com/file/CbNZdWaWBgjxaN6BnX6xva/Aerie-%231128---Model-Specifications-(Constraints%2C-Goals%2C-Conditions)?type=design&node-id=64-30615&mode=design&t=WecElOFTI6JWGkZ5-4

Remaining design items here:

1. How do we handle responsiveness + long goal names?
2. How can we include version tags as these are some of the best "names" or identifiers

Showing goals, constraints, and conditions in the plan needs a bit more design work, but is getting close.

1. How do we ensure long names show up in a readable way?
2. How do we prompt or notify the user that they're out of sync with the model? Should probably include some notification outside of the panel itself.
3. How do we communicate syncing options?

[lklyne]

@duranb ready to roll here!

[dandelany]

Thanks @lklyne ! Will open a new ticket for implementation