ssheleg/super-ux

ux-foundation

Use when defining who uses a product and why (docs/ux/foundation.md): personas, actors, JTBD, journeys, stories, capabilities, churn.

소스 보기

사용 방법

  1. 설치 명령을 복사하고 자신의 에이전트 환경에 설치하기 전에 소스 패키지를 확인하세요.
  2. 필요한 도구, 인증 정보, 지원 환경은 원본 문서에서 확인하세요.
  3. 입력과 원하는 산출물을 설명하고 출처와 결과를 대조하세요.
npx skills add https://github.com/ssheleg/super-ux --skill ux-foundation

시작 전 확인

  • 설치에는 모델 구독, API 한도, 파일 접근 권한이 포함되지 않습니다.
  • 별점 수와 설치 수는 활동 지표이며 독립적인 품질·보안 검증이 아닙니다.
원본 Skill 문서

원본 저장소의 제목, 예시, 코드, 표, 링크, 이미지를 유지해 표시합니다.

ux-foundation — The WHY Layer

Part of super-ux — see system-map.md for the whole pipeline (foundation → capabilities → 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 v5; a v4 chain stays valid until it opts in). 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

SituationWorkflow
No foundation.md, new productInit (interview)
No foundation.md, existing product/scenariosInit (reverse)
Understanding of users changedUpdate
Consistency questioned; before building on topValidate

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)

  1. 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)

  1. 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)

  1. Derive user stories from journey pains and job outcomes; write

acceptance criteria; prioritize must/should/could against the job's success metric.

  1. Record Design tooling when the first human surface is about to be

designed (never for a capability no person sees): 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.

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

  1. 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).

  1. Present layer by layer for approval (under delegated mode in

system-map.md, record the approval and continue); mark unvalidated guesses as assumptions with a risk note.

Capabilities (contract v5)

Under contract v5 (new projects start there; a v4 chain opts in on its first capability task, as docs/ux/doctor.py says) this skill also owns the layer between the stories and the flows. Field rules: the contract's Contract v5: agents and capabilities in scenario-format.md.

  1. Actors. List who else performs the work under ## Actors: an agent

acting for a persona, an automation, an outside system (A-NN, Kind, Acts for, Grant). Give each persona Agent use: none | some | most with its evidence, and each journey stage its Performed by.

  1. Stories → capabilities. Seed docs/ux/capabilities.md from

templates/capabilities.md; every must/should story gets a CAP-NN, one row per effect set (a refund is its own row beside a cancellation), filled in the contract's order. none is an answer; a blank is not.

  1. Parity first (AN-1). An agent can do what a person can, acting and

being notified, unless the row names why not: presence, legal, or debt (B-nnn) with its board row.

  1. Why a person (AN-4). A person enters at a gate (body, approval,

legal) or for a serving reason (oversight, exception-queue, trust, presence, audience, manual, taste), each with its evidence. A persona with Agent use: none keeps a whole human path. No gate, no reason and a determinable trigger: an automation (AN-6).

  1. The agent panel. When the agent surface will be tested, seed

docs/ux/agent-panel.md from templates/agent-panel.md: five agents, each with its grant and the scenarios it walks.

  1. Hand off. The contract the agents and the interface call is

agent-stack's (agent-surface.md, <https://raw.githubusercontent.com/ssheleg/agent-stack/main/plugins/agent-stack/skills/agent-interop/references/agent-surface.md>); flows and screens for the human lanes go to ux-flows, agent-channel scenarios to ux-scenarios.

Init (reverse) — existing product

  1. Inventory what exists: scenarios.md (if any), screens/routes, onboarding,

settings, analytics/support artifacts when available.

  1. 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).

  1. Flag the gaps loudly: features serving no discernible job (candidates to

cut), jobs with no support (opportunities), journey stages with pain and no coverage.

  1. 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 evidencekind — 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 validationstatus 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.

  1. Quality: JTBD statements are situation/motivation/outcome (no

features); stories INVEST; acceptance criteria observable; journeys have all layers filled.

  1. 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) and, under v5, ≥1 capability (U089).

  1. 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 → capabilities (v5) → ux-flows turns

them into user flows for the human lanes 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.

같은 저장소의 Skills

더 많은 Skills

모든 Skills
ssheleg
커뮤니티

copywriting

Use when writing text a user reads: UI strings, landings, store listings, posts, ads, email. Triggers: "напиши текст", "App Store description" / "описание для App Store", "video hook" / "хук ролика". Not for the voice (brand-voice) or look (sheleg-design). Refusal phrase "no brand" / «без бренда».

1시간 설치 수
1
GitHub Stars
8
업데이트
11월 11일
ssheleg
커뮤니티

ux-audit

Use when verifying the codebase against the UX scenario base (batched, evidence-backed, report in docs/ux/audits/). Triggers: "ux audit" / "UX-аудит", "run the scenarios" / "прогони по сценариям". Not for a whole-project audit (project-audit) or editing scenarios (ux-scenarios).

1시간 설치 수
1
GitHub Stars
8
업데이트
11월 11일
ssheleg
커뮤니티

ux-flows

Use when designing how users move through a product: flows, screen states, wireframes, Figma mockups, funnels, paywalls. Triggers: "юзер флоу", "add a screen" / "добавь экран", "mockups" / "макеты". Not for the visual system (sheleg-design). Refusal phrase "no scenarios" / «без сценариев».

1시간 설치 수
1
GitHub Stars
8
업데이트
11월 11일
ssheleg
커뮤니티

ux-scenarios

Use when writing UX scenarios (docs/ux/scenarios.md): a new feature, a user-facing behavior change, a move to scenario-driven development. Triggers: "ux scenarios" / "сценарии использования", "новая фича". Not for an empty project (vision first). Refusal phrase "no scenarios" / «без сценариев».

1시간 설치 수
2
GitHub Stars
7
업데이트
11월 11일