ux-foundation

ux-foundation — The WHY Layer

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

Interfaces fail when built without knowing WHO uses them and WHY. This skill maintains docs/ux/foundation.md: Personas → Jobs to Be Done → Customer journeys → User stories. Scenarios (ux-scenarios skill) are built on top and trace to these IDs — the full chain gives every scenario its context.

Format contract: scenario-format.md (ux-contract v4). Never deviate from ID schemes or field names.

The chain's opt-out is spoken: an operator saying "no scenarios" / «без сценариев» declines the scenario-first route — proceed without the chain and say so, never drop it silently.

Quality bars (non-negotiable)

• Personas are grounded in data or observation, recognizable by a real user — not invented archetypes with stock-photo traits.
• JTBD statements name a situation, motivation, and outcome — never a feature ("When I land a new client, I want to start a clean workspace, so I can bill them separately" — not "I want a projects dropdown"). Capture the four forces: push, pull, anxiety, habit.
• Journeys cover the end-to-end experience (before, during, after the product), one row per stage: action, touchpoint, emotion (1–5), pain, opportunity. Score opportunities Frequency × Severity × Solvability. When filling opportunities, consult best-practices.md by stage tags for proven mechanisms.
• Which model is being applied, and where it lies. product-frameworks.md (PF-01..PF-12) carries the named models this layer draws on, each with the failure mode that makes it worth knowing: the forces that explain why people do not switch, the interview that produces them, the tree that makes two solutions comparable, and the activation definition every onboarding design depends on. Two are ordering constraints rather than inputs: PF-07 before any onboarding work, and PF-02 before PF-01.
• On a paid-acquisition product, the market read comes before the personas are written, because the buyer arrives through somebody's ad and the category has already paid to learn who answers it. funnel-research.md is the method: FR-01 collects the live funnels, FR-02 reads the four signals that survive when revenue is invisible, FR-05 names which adjacent categories transfer. Its FR-07 lands each finding here rather than in a document of its own. It informs the personas; it never decides them — a foundation built from a corpus alone is aimed at a competitor's audience.
• Stories pass INVEST; acceptance criteria are Given/When/Then and observable. A story that can't be verified is not done being written.
• Evidence beats opinion: repeated pain across users, observable workarounds, measurable cost. One stakeholder's idea is an assumption, not a fact — mark assumptions (desirability / viability / feasibility / usability) and flag the risky-untested ones.
• Reviews and support tickets are evidence already sitting there. Before scheduling interviews nobody has time for, read the store reviews and the support queue and sort them into praise, feature requests, bugs, and friction complaints. The friction complaints are journey pain in the user's own words — cite the source and the date on the journey row, the way any other evidence is cited. This is the cheapest input the WHY layer has and the one most often skipped because it does not feel like research.