git:20260831.3e921f6 to git:20260831.5890f87

---

name: ux-foundation

description: Use when defining or revising WHO the users are and WHY they use the product - personas, Jobs to Be Done, customer journey maps, user stories with acceptance criteria. A journey covers the end-to-end experience including what happens after the first session - where a user comes back, where user retention is won, and where churn actually starts. Maintains docs/ux/foundation.md, the WHY layer that UX scenarios trace to. Triggers - "jtbd" / "джобы", "customer journey" / "карта пути", "user story" / "юзер стори", "personas" / "персоны", "who is this for", "user retention" / "ретеншн", "churn" / "отток", new product discovery.

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.

## 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](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.

- **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) and the project's Figma file URL — the two

fields this file owns. 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 validation; inferred entries stay marked until the user

confirms them.

## 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.

## 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.