129 lines
3.5 KiB
Markdown
129 lines
3.5 KiB
Markdown
# Mental Model: Asset Mutations
|
|
|
|
## The Problem
|
|
|
|
Asset mutations are easy to get wrong in a Studio UI.
|
|
|
|
Why?
|
|
|
|
Because some actions only update registry state, while others change the physical workspace.
|
|
|
|
If the Studio hides that difference, users lose trust quickly.
|
|
|
|
## The Rule
|
|
|
|
Sensitive asset mutations are `preview-first`.
|
|
|
|
That is the most important rule.
|
|
|
|
The Studio must not perform destructive or relocational asset changes as if they were harmless button clicks.
|
|
|
|
## What The User Must Understand Before Apply
|
|
|
|
Before applying a mutation, the user should be able to answer:
|
|
|
|
- Which assets are affected?
|
|
- Is this touching only the registry, or also the workspace?
|
|
- Will something be created, moved, or deleted?
|
|
- Are there blockers?
|
|
- Are there warnings?
|
|
- Is this a safe fix or a risky mutation?
|
|
|
|
If the UI cannot answer those questions, the mutation flow is not ready.
|
|
|
|
## Why Inline Review Is The Baseline
|
|
|
|
The default review surface is an inline staged panel, not a modal.
|
|
|
|
That keeps the user anchored in the asset and its surrounding context.
|
|
|
|
It lets the user compare:
|
|
|
|
- the selected asset,
|
|
- the diagnostics,
|
|
- the proposed changes,
|
|
- and the action consequences
|
|
|
|
without bouncing between unrelated windows.
|
|
|
|
## Why Modals Still Exist
|
|
|
|
Modals are still useful, but only for high-risk final commits.
|
|
|
|
Examples:
|
|
|
|
- destructive delete;
|
|
- major relocation;
|
|
- other strongly irreversible actions.
|
|
|
|
The mistake would be using modals as a substitute for review.
|
|
|
|
Preview is the review.
|
|
|
|
Modal confirmation is only the final safety gate when the risk is high enough.
|
|
|
|
## The Most Important Distinction
|
|
|
|
The Studio must distinguish:
|
|
|
|
- registry impact
|
|
- workspace impact
|
|
|
|
This is one of the most important didactic duties of the asset workspace.
|
|
|
|
A user should never have to guess whether a button:
|
|
|
|
- merely forgets an asset from management,
|
|
- or actually deletes or moves files.
|
|
|
|
## Blockers, Warnings, and Safe Fixes
|
|
|
|
These categories must stay visually and semantically separate.
|
|
|
|
They are not interchangeable kinds of “message”.
|
|
|
|
- `blockers` stop the apply path;
|
|
- `warnings` tell the user the action is still meaningful but risky or noteworthy;
|
|
- `safe fixes` are low-risk corrections and should not be grouped as if they were destructive operations.
|
|
|
|
If those three collapse into one list, users stop trusting the flow.
|
|
|
|
## Batch Operations
|
|
|
|
Batch operations are not just “single asset, repeated many times”.
|
|
|
|
They need:
|
|
|
|
- an aggregate summary first,
|
|
- then drill-down detail.
|
|
|
|
Without that, the flow becomes unreadable and users either miss risk or abandon the tool.
|
|
|
|
## How Activity Fits In
|
|
|
|
The preview itself belongs to the workspace.
|
|
|
|
But the shell should still reflect lifecycle milestones such as:
|
|
|
|
- preview ready;
|
|
- action applied;
|
|
- action failed.
|
|
|
|
That way the workspace remains the place of review, while the shell keeps the broader operational timeline visible.
|
|
|
|
## Common Failure Modes
|
|
|
|
Avoid these:
|
|
|
|
- destructive apply without preview;
|
|
- using raw logs as the main explanation surface;
|
|
- mixing safe fixes with deletes;
|
|
- showing technical diff data with no user-facing interpretation;
|
|
- forcing the user into modal-only flows for ordinary review.
|
|
|
|
## Read With
|
|
|
|
1. [`../specs/4. Assets Workspace Specification.md`](../specs/4.%20Assets%20Workspace%20Specification.md)
|
|
2. [`mental-model-assets-workspace.md`](./mental-model-assets-workspace.md)
|
|
3. [`../../packer/specs/5. Diagnostics, Operations, and Studio Integration Specification.md`](../../packer/specs/5.%20Diagnostics,%20Operations,%20and%20Studio%20Integration%20Specification.md)
|