ux-scenarios

ux-scenarios — Maintain the Scenario Base

Part of super-ux — see system-map.md for the whole pipeline and the four sync rules. After changes, run the linter (python3 docs/ux/lint.py).

AI-generated interfaces go bad when UI is built without a model of user behavior. This skill keeps one: docs/ux/scenarios.md in the target project is the source of truth for everything the user can do, see, and hit — every feature, every button, every state, every error, every result.

Format contract: scenario-format.md (ux-contract v4). Read it before writing or editing scenarios. Never deviate from its field names, ID rules, statuses, or checklists.

The WHY and HOW layers: when docs/ux/foundation.md exists (personas, JTBD, journeys, stories — ux-foundation skill) and/or docs/ux/flows.md (task analysis, user flows — ux-flows skill), scenarios are derived FROM them: one scenario set per flow, covering the happy path, every error edge, and every alt branch of the flow diagram; Traces: filled with story + flow IDs; traceability rules enforced (every must/should story covered; every flow node/edge covered; every scenario serves a story or job — a scenario serving nothing is a candidate for deletion, not implementation). Steps are written use-case style: user action -> observable system response. If the upper layers are missing on a non-trivial product, recommend ux-foundation → ux-flows first; proceed in v1 mode (no Traces) only for tiny projects or on explicit user choice.

Design taste: apply ux-design-principles.md — states per screen, error recovery, primary-action rules — when writing Expected results and Errors & recovery.

The hard rule

1. Scenarios come BEFORE interface. A new feature or project starts with drafting scenarios and validating them against the existing base — conflicts, overlaps, gaps — and getting them approved. Only then design and build UI.
2. Any change touching user-facing behavior updates docs/ux/scenarios.md in the SAME change. New behavior with no scenario is a blocker, not a warning.

The opt-out is spoken, never assumed: the operator declines this route by saying "no scenarios" / «без сценариев» — proceed without the base and say so in the delivery, rather than skipping it silently.

Best practices: when drafting or reviewing scenarios, consult best-practices.md — filter by tags matching the feature/journey stage (onboarding, paywall, retention, …) and the product domain. Apply a practice only when it serves a traced job/story; note applied practice IDs (BP-NNN) in the scenario's design rationale. The catalog is living — new proven practices get appended per its "How to add" rules.

Choosing a workflow

Situation	Workflow
No docs/ux/scenarios.md, little or no code	Init (greenfield)
No docs/ux/scenarios.md, existing product code	Init (existing code)
Base exists; behavior is being added/changed	Update
Base exists; consistency questioned, or a new feature idea arrives	Validate

Announce which workflow you are running. If docs/ux/ is missing, create it (seed scenarios.md from this skill's own templates/scenarios.md).

Init (greenfield)

Scenarios are designed here, not reverse-engineered.

1. Interview the user, one question at a time: who are the personas? what job does each hire the product for? what are the core features? what must never happen to the user?
2. Draft personas, then scenarios feature by feature. For every feature, satisfy the per-feature completeness checklist (happy path, every error path, empty state, visible loading, destructive-action confirmation, returning-user variant) and the per-product checklist (first-run onboarding through multi-entity flows) from the format contract.
3. All entries start as Status: draft, Coverage: none yet, Product: unobserved. The last one is the outcome state and it stays unobserved until a signal from the world arrives — shipping the scenario does not move it, and neither does an audit passing on it.
4. Present the base to the user section by section for approval. Approved scenarios move to validated.
5. Only after validation of the scenarios a screen DEPENDS ON may its UI design/implementation begin — pointed at those scenarios. The build state is ux-flows' four-state machine (full / provisional / tooling-degraded / declined): an approved text spec builds even with optional Figma absent (deferred frame sync), a serious unknown blocks only its dependent screens, and approvals recorded here count in every layer without re-running the chain.

Init (existing code)

The base must cover everything that exists, then expose the gaps.

1. Inventory sweep of the codebase (dispatch parallel Explore/general subagents for large codebases, one area each): routes and screens; interactive elements (buttons, forms, dialogs, menus); state branches (loading / empty / error / success); error paths and what the user sees; onboarding and first-run logic; settings; multi-entity flows.
2. Draft scenarios from the inventory, feature by feature, filling Coverage: with the file:line evidence found during the sweep.
3. Flag both gap directions explicitly in your report to the user:
   • code behavior with no scenario (was invented ad hoc — now captured);
   • checklist items with no code (e.g. no empty state exists at all) — record these as draft scenarios with Coverage: none yet.
4. Present for validation as in greenfield step 4.

Update

Given a change (a diff, a feature description, a bug fix):

1. Identify affected scenarios by feature and UI elements. Search the base — don't trust memory.
2. Apply edits: adjust steps/elements/errors of existing scenarios; add new scenarios for new behavior; retire scenarios that are no longer true (Status: retired + one-line reason — never delete).
3. Changed scenarios drop back to draft until re-approved; keep the Index table in sync.
4. If the change introduced user-facing behavior that fits NO scenario even after this pass, stop and say so — that behavior needs a scenario decision before it ships.

Validate

Consistency pass over the base (also run before approving any new feature idea):

1. Integrity: IDs sequential and unique; Index matches entries; every referenced persona defined; statuses legal.
2. Coverage: every feature meets the per-feature checklist; the product meets the per-product checklist. List what's missing.
3. Traceability (when foundation.md exists): every must/should story has ≥1 scenario; every scenario traces to ≥1 story or job; every journey stage with a product touchpoint has ≥1 scenario. Orphans in either direction are findings.
4. Conflicts: scenarios that contradict each other (same entry point, incompatible outcomes; same element, different behavior). For a new feature idea: validate against the foundation first (which job does it serve? which journey stage?), then against existing scenarios — propose reconciliation before any UI work. An idea serving no job is challenged, not silently accepted.
5. Report findings as a checklist with per-item fixes; apply approved fixes.

Moderated test tasks from the base (on request)

For a multi-screen journey, recommend a clickable scenario preview alongside the base; when requested, it is a deliverable. Follow interactive-flow-prototypes.md. The preview may refine draft scenarios before production approval: trace each case to screen-states and transitions, include alternative/error/recovery paths, and keep declared coverage separate from observed clickthrough. A simulated success does not change implementation Coverage or Product outcome status.

A scenario is already the shape a usability-test task wants: a situation, a goal, and an observable success condition. Turning one into the other is a rewrite, not a new artifact — so when someone is about to test with users, generate the tasks from the base rather than writing them fresh.

Per scenario in scope:

• Scenario — the situation in the participant's terms, never the product's: "you have just been handed a project from a colleague", not "open SCN-014".
• Goal — what they are trying to achieve, stated without naming the UI that achieves it. "Find the settings" is a leading task; "change where notifications are sent" is a task.
• Success — the observable end state, taken from the scenario's Expected result.

Rules that keep the tasks honest: no verb from the interface in the wording (no "click", "tap", "the X button"), warm-up first and edge cases last, and one task per scenario — a task that needs two goals is two tasks. Where the scenario has alt or error paths, they become the stress tasks.

What comes back is graded against the same base: a task nobody completes is a finding against its scenario, not against the participant.

Definition of done

• Index, personas, and entries in sync; format contract honored.
• The user has seen and approved new/changed scenarios (validated).
• Gaps and conflicts reported honestly — never silently dropped.

What else is in references/. This skill names 5 contract(s) directly; references/ holds 13, because a contract this skill names links others and the whole closure ships inside the skill — the skills CLI installs one directory and a sibling's file would arrive dangling. Open the ones named here; the rest are reached from them, by name, when a contract sends you.