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.

Triggers

The phrases that route to this skill, in English and Russian. The description keeps only the strongest of them so the skill listing stays inside its budget (2026-10-20); the family routing hook matches this list.

"jtbd" / "джобы", "customer journey" / "карта пути", "user story" / "юзер стори", "personas" / "персоны", "who is this for", "user retention" / "ретеншн", "churn" / "отток", new product discovery.

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. Record the map Owner (or unknown) under the format contract; writing the map does not assign its author. Score opportunities Frequency × Severity × Solvability — and each factor carries its SOURCE and SCALE, or the value is unknown; a factor nobody has measured is never a number invented to fill the cell, and emotion (1–5) likewise records who reported it (owner belief vs an observed session), not a guess dressed as a rating. 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.
• Every finding lands with its provenance. Read research-evidence.md when synthesizing research or writing any number into a foundation document: observation, citation, inference and hypothesis are separate classes; contradictory participants stay linked; a number travels with unit, entity, population and date; and what has no data stays a hypothesis — there is no quota of evidence. A synthetic persona or an LLM "digital twin" is never evidence: its output is a hypothesis until real users or real data confirm it.
• The ledger is local, and it is not a new route. It lives at docs/ux/research-ledger.md, beside the foundation it feeds — research synthesis is a step INSIDE foundation work, never a separate pipeline. A transcript already on disk is a complete input: no Notion, no Dovetail, no browser and no API key is needed to turn local material into ledger rows, and a synthesis that stalls waiting for a tool it does not need has invented a dependency.
• Evidence ids and unknowns travel into the scenarios. A persona trait or journey stage cites the RE- ids that support it, and the scenarios built on top RETAIN those ids — the trace chain carries provenance, not just structure. A hypothesis that shaped a scenario rides along as an explicit unknown in that scenario; dropping it on the way is how a guess arrives in the interface wearing a fact's clothes.
• 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.

Choosing a workflow

If docs/ux/ is missing, create it; seed foundation.md from this skill's own templates/foundation.md.

Init (interview) — greenfield

One question at a time; user's answers are the data:

1. Who will use this? (→ personas; probe until each is concrete enough to recognize)
2. Per persona: what situation triggers them to reach for the product? What are they really trying to get done? What outcome tells them it worked? (→ JTBD + forces)
3. Walk their path end-to-end, before/during/after: where do they start, what do they touch, where does it hurt today? (→ journeys, emotion + pain per stage)
4. Derive user stories from journey pains and job outcomes; write acceptance criteria; prioritize must/should/could against the job's success metric.
5. Record Design tooling when design work is about to start: the Figma on/off choice (default on), the product's Figma folder, and one file per surface the product has — App, Web, ASO — the fields this file owns. One URL for everything is how the store art and the site end up with no recorded home. Everything else about the visual layer (design system, style pack, per-state frame links) lives in screens.md; see figma-integration.md and visual-identity.md. Ask the Figma question once per project, never per flow.
6. Record Product mechanics when any of the three applies (contract §7): personalization, engagement mechanics (streaks/points/leaderboards), and the accessibility regime the product ships under. "None" is a valid answer and worth recording — practice selection reads these three and cannot infer them from the rest of the chain.
7. If the product earns money, fill the Monetization section: model chosen with data (BP-067..070 — hard paywall vs freemium vs hybrid, trial type and length), value metric, free boundary, purchase surface (IAP, web checkout, or web2app — BP-030/BP-078/BP-127), money moments, acquisition coherence. Money moments become dedicated flows downstream; a web or web2app purchase surface makes the web funnel and the paid handoff flows of this product too (BP-116..129).
8. Present layer by layer for approval; mark unvalidated guesses as assumptions with a risk note.

Init (reverse) — existing product

1. Inventory what exists: scenarios.md (if any), screens/routes, onboarding, settings, analytics/support artifacts when available.
2. Reverse-engineer: what jobs does the current UI implicitly serve? Which personas does it assume? Draft JTBD/journeys/stories from evidence, tag confidence (observed vs inferred).
3. Flag the gaps loudly: features serving no discernible job (candidates to cut), jobs with no support (opportunities), journey stages with pain and no coverage.
4. Present for a DECISION, not to launder the evidence. Three axes stay separate (references/scenario-format.md): evidence_kind (brief / owner-belief / interview / telemetry / code-inference), decision_status (proposed / accepted / rejected), and validation_status (unvalidated / observed / contradicted). An owner saying "I confirm" moves DECISION to accepted; it does NOT change evidence_kind — an accepted persona whose only evidence is owner-belief is still unvalidated, and the record says so. Only a real interview or observation, with its DATED receipt, moves validation_status to observed. A founder cannot promote a wished-for persona to observed by approving it.

Update

Given new knowledge (user feedback, analytics, pivot, new segment):

1. Locate affected entries by ID; update statements, stages, stories.
2. Dropped directions: mark stories dropped, keep entries — never delete.
3. Cascade check: which scenarios trace to the changed IDs? List them and hand the list to ux-scenarios (Update) in the same session.

The test panel

When a project changes an interface through task-pipeline, its design-tester walks a test panel: docs/ux/test-panel.md, ten portraits from templates/test-panel.md. Build it from the foundation: one portrait per persona first, then fill to ten across activation stages (new, activating, active, at risk, returning) and the needs that change a screen (small phone, large text, keyboard only, a second locale, a slow connection). At least two portraits are locals (high engagement, connected data, arrived through a friend) and at least two are tourists (low engagement, arrived through an ad or a discount), marked at the start of the retention line: lifetime value rests on the first, churn comes mostly from the second (the split is in references/funnel-research.md, Your own numbers). Each portrait carries its features, two to four composite scenarios by SCR- id, its activation funnel and its retention loop, and a basis line: evidence RE-NN or hypothesis. The panel is a test instrument: the quality bar above still holds, so a hypothesis portrait decides what to test, never what to build. The operator confirms the panel once; a product change revises it. Its gate is task-pipeline's design_gate.py panel docs/ux/test-panel.md.

Validate

1. Integrity: IDs sequential/unique; every story traces to a job; every journey belongs to a persona × job; statuses legal.
2. Quality: JTBD statements are situation/motivation/outcome (no features); stories INVEST; acceptance criteria observable; journeys have all layers filled.
3. Coverage: every persona has ≥1 job; every job has ≥1 journey and ≥1 story; every must/should story has ≥1 scenario in scenarios.md (or is explicitly awaiting one).
4. Report as a checklist with per-item fixes; apply approved fixes.

Definition of done

• Layers consistent, IDs stable, assumptions marked as such.
• The user approved new/changed entries.
• Cascading updates identified and handed downstream (ux-flows for affected flows, ux-scenarios for affected scenarios) — the chain never silently drifts.
• Next layer offered: stories ready → ux-flows turns them into user flows before any UI work.

What else is in references/. This skill names 8 contract(s) directly; references/ holds 14, 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.