git:20261022.ad18d60 to git:20261025.d4c4de4

---

name: ux-foundation

compatibility: Any agent with file read/write. The closing lint (python3 docs/ux/lint.py, seeded by this pack) needs python3 3.9+, stdlib only - nothing to pip install. The Figma on/off choice recorded in step 5 needs no tooling of its own - the Figma MCP matters downstream, in ux-flows.

license: MIT

---

# ux-foundation — The WHY Layer

> Part of **super-ux** — see [system-map.md](references/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](references/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](references/best-practices.md) by stage tags for

proven mechanisms.

- **Which model is being applied, and where it lies.**

[product-frameworks.md](references/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](references/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](references/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

| Situation | Workflow |

|---|---|

| No `foundation.md`, new product | Init (interview) |

| No `foundation.md`, existing product/scenarios | Init (reverse) |

| Understanding of users changed | Update |

| Consistency questioned; before building on top | Validate |

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](references/figma-integration.md) and

[visual-identity.md](references/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`](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`](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.