ux-foundation

ux-foundation — WHY 层

属于 super-ux — 请参阅 system-map.md， 了解完整流程（foundation → flows → screens → scenarios → audits → plans）以及四条同步规则。更改后，运行检查器 （python3 docs/ux/lint.py）。

构建界面时，若不了解使用者是谁、为什么使用，界面就会失败。此技能维护 docs/ux/foundation.md：用户画像 → 待完成任务（JTBD）→ 客户旅程 → 用户故事。 场景（ux-scenarios 技能）基于此构建，并追溯到这些 ID — 完整链条为每个场景提供上下文。

格式约定： scenario-format.md （ux-contract v4）。绝不能偏离 ID 规则或字段名称。

退出此链条必须明确说出： 操作者表示 “no scenarios” / «без сценариев»，即拒绝以场景为先的路径 — 此时继续操作，但不使用此链条，并明确说明，绝不能悄悄省略。

触发词

会将请求路由到此技能的短语，包含英文和俄文。技能描述只保留其中最有代表性的短语，以确保技能列表不超出预算（2026-10-20）；系列路由钩子与此列表匹配。

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

质量标准（不可妥协）

• 用户画像应基于数据或观察，真实用户能够认出自己，而不是凭空编造、带着图库照片特征的原型。
• **待完成工作（JTBD）**陈述应说明情境、动机和结果，而不是功能（“当我签下一位新客户时，我想新建一个干净的工作区，这样就能单独向他们收费”——而不是“我想要一个项目下拉菜单”）。记录四种力量：推动、吸引、焦虑、习惯。
• 用户旅程应覆盖端到端体验（使用产品之前、期间和之后），每个阶段一行，包含：行动、触点、情绪（1–5）、痛点、机会。根据格式约定记录地图负责人（或 unknown）；撰写地图并不意味着作者就是负责人。按频率 × 严重程度 × 可解决性为机会评分——每个因素都必须附带其来源和量表，否则值为 unknown；从未测量的因素绝不能为了填满单元格而编造一个数字。情绪（1–5）同样要记录是谁报告的（负责人判断还是观察所得的访谈记录），不能把猜测伪装成评分。填写机会时，按阶段标签查阅 best-practices.md，了解经过验证的机制。
• 应用的模型是什么，它们又有哪些局限。 product-frameworks.md （PF-01..PF-12）列出了这一层采用的模型，并说明了它们值得了解的失效模式：解释人们为何不转换的各种力量、能挖掘这些力量的访谈、让两种解决方案可进行比较的树，以及所有引导流程设计都依赖的激活定义。其中两项是顺序约束，而非输入：任何引导流程工作都必须先完成 PF-07，PF-01 之前必须先完成 PF-02。
• 对于付费获客产品，应先了解市场，再撰写用户画像，因为买家是通过某个人的广告到来的，而这个品类已经花钱弄清了哪些人会响应。 funnel-research.md 介绍了具体方法：FR-01 收集现有的营销漏斗，FR-02 解读收入数据不可见时仍然有效的四种信号，FR-05 指出哪些相邻品类的经验可以迁移。FR-07 将每项发现归入此处，而不是另行记录在一份独立文档中。市场调研为用户画像提供信息，但绝不替它们做决定——仅基于语料构建的基础，是在瞄准竞争对手的受众。
• 每项发现都必须附上其来源。 在综合研究或向基础文档中填写任何数字时，请阅读 research-evidence.md：观察、引用、推断和假设是不同的类别；相互矛盾的参与者信息仍需保持关联；数字必须附带单位、实体、总体和日期；没有数据的内容就保留为假设——证据没有配额。合成用户画像或 LLM“数字孪生”绝不算证据：在真实用户或真实数据确认之前，其输出都只是一个假设。
• 台账是本地的，不是新增的流程。 它存放在 docs/ux/research-ledger.md，与其所支持的基础文档并列——研究综合是基础工作内部的一步，而不是独立的流程。磁盘上已有的访谈记录就是完整输入：不需要 Notion、Dovetail、浏览器或 API 密钥，也能将本地资料整理成台账条目；综合工作若因等待并非必需的工具而停滞，就是凭空制造依赖。
• 证据 ID 和未知项应延续到场景中。 用户画像特征或旅程阶段应引用支持它的 RE- ID，基于这些内容构建的场景也应保留这些 ID——追溯链承载的是来源信息，不只是结构。影响场景的假设应作为明确的未知项保留在该场景中；若途中将其丢弃，猜测就会穿上事实的外衣出现在界面里。
• 用户故事应符合 INVEST 原则；验收标准应采用 Given/When/Then 格式且可观察。无法验证的故事，说明还没有写完。
• 证据胜于意见：多个用户反复遇到的痛点、可观察到的变通做法、可衡量的成本。某位利益相关者提出的想法只是一个假设，而非事实——应标记假设（期望性／可行性／技术可行性／可用性），并标出尚未验证且风险较高的假设。
• 评论和支持工单本身就是现成的证据。 在安排没人有空参加的访谈之前，先阅读应用商店评论和支持队列，并将内容归类为好评、功能请求、Bug 和操作障碍投诉。操作障碍投诉就是用户用自己的话描述的旅程痛点——与引用其他证据一样，在旅程条目中注明来源和日期。这是 WHY 层成本最低的输入，也是最常被跳过的一项，因为它看起来不像研究。

选择工作流

情况	工作流
没有 foundation.md，新产品	初始化（访谈）
没有 foundation.md，已有产品／场景	初始化（逆向分析）
对用户的理解发生变化	更新
对一致性有疑问；在此基础上继续构建之前	验证

如果缺少 docs/ux/，请创建该目录；并使用此技能自身的 templates/foundation.md 创建初始版 foundation.md。

初始化（访谈）——从零开始

每次只问一个问题；用户的回答就是数据：

1. 谁会使用这个产品？（→ 用户画像；持续追问，直到每个画像都具体到可以识别）
2. 对每个用户画像：什么情境会促使他们使用这个产品？他们真正想完成什么？什么结果能说明产品奏效了？ （→ JTBD + 驱动力）
3. 从头到尾梳理他们的路径，覆盖之前／期间／之后：他们从哪里开始、会接触什么、目前哪里让他们感到困扰？ （→ 用户旅程，以及每个阶段的情绪 + 痛点）
4. 根据旅程中的痛点和工作目标的结果推导用户故事；撰写验收标准；参照工作目标的成功指标，按必须／应该／可以优先排序。
5. 即将开始设计工作时，记录 设计工具：是否使用 Figma（默认开启）、产品的 Figma 文件夹，以及产品每个界面对应的一个文件 — App、Web、ASO — 并注明各文件负责记录哪些字段。所有内容都只用一个 URL，会导致商店素材和网站最终都没有记录归属位置。视觉层的其他内容（设计系统、样式包、各状态的画面链接）记录在 screens.md 中；参见 figma-integration.md 和 visual-identity.md。每个项目只问一次 Figma 相关问题，不要对每个流程都问。
6. 符合以下任意一项时，记录 产品机制（契约 §7）：个性化、互动机制（连续打卡／积分／排行榜），以及产品采用的无障碍规范。“无”也是有效答案，值得记录 — 实践选择会读取这三项，无法从链条中的其他内容推断得出。
7. 如果产品通过收费盈利，填写变现部分：根据数据选择的模式（BP-067..070 — 硬付费墙 vs 免费增值 vs 混合模式、试用类型和时长）、价值指标、免费范围、购买界面（IAP、Web 结账或 web2app — BP-030/BP-078/BP-127）、付费时机、获客一致性。后续流程会为付费时机设置专门的流程；Web 或 web2app 购买界面也意味着该产品还包含 Web 转化漏斗和付费交接流程（BP-116..129）。
8. 按层展示并逐层征求批准；将未经验证的猜测标记为假设，并附上风险说明。

初始化（逆向分析）——已有产品

1. 盘点现有内容：scenarios.md（如有）、屏幕／路由、引导流程、设置，以及可用时的分析／支持材料。
2. 逆向分析：当前 UI 隐含地服务于哪些工作目标？它假定了哪些用户画像？根据证据起草 JTBD／用户旅程／用户故事，并标注置信度（观察所得 vs 推断所得）。
3. 明确指出差距：服务于无法识别的工作目标的功能（可考虑删减）；缺少支持的工作目标（潜在机会）；存在痛点但没有覆盖的旅程阶段。
4. 展示内容以供决策，而不是粉饰证据。三个维度必须分开（references/scenario-format.md）：evidence_kind （brief / owner-belief / interview / telemetry / code-inference）、 decision_status（proposed / accepted / rejected）和 validation_status（unvalidated / observed / contradicted）。负责人说“我确认”会将决策状态改为 accepted；但不会改变 evidence_kind — 如果某个已接受的用户画像只有 owner-belief 作为证据，它仍然是 unvalidated，记录中也必须如实说明。只有真实访谈或观察，且留有注明日期的凭据，才能将 validation_status 改为 observed。创始人不能通过批准，将一个理想化的用户画像升级为 observed。

更新

出现新知识（用户反馈、分析数据、方向调整、新细分市场）时：

1. 按 ID 查找受影响的条目；更新陈述、阶段和故事。
2. 已放弃的方向：将故事标记为 dropped，保留条目——切勿删除。
3. 检查级联影响：哪些场景可追溯到已更改的 ID？列出这些场景，并在同一会话中将列表交给 ux-scenarios（Update）。

测试面板

当项目通过 task-pipeline 更改界面时，其 design-tester 会检查一份测试面板：docs/ux/test-panel.md，包含来自 templates/test-panel.md 的十个人物画像。先从基础开始构建：每种用户画像先对应一个人物画像，再根据激活阶段（新用户、激活中、活跃、有流失风险、回归）以及会改变屏幕的需求（小屏手机、大号字体、仅用键盘、另一种语言环境、网络连接缓慢）补足至十个。至少两个人物画像是本地用户（高参与度、数据已关联、经朋友介绍而来），至少两个人物画像是游客（低参与度、通过广告或折扣活动而来），并在留存线的开端标明：终身价值主要来自前者，流失大多来自后者（细分见 references/funnel-research.md 中的 Your own numbers）。每个人物画像都包含其特征、两个到四个带有 SCR- ID 的复合场景、其激活漏斗和留存循环，以及依据说明：evidence RE-NN 或 hypothesis。该面板是一种测试工具：上述质量标准仍然适用，因此假设性人物画像用于决定要测试什么，而不是决定要构建什么。操作者只需确认一次面板；产品变更时再修订。面板的门禁是 task-pipeline 的 design_gate.py panel docs/ux/test-panel.md。

验证

1. **完整性：**ID 连续且唯一；每个故事都可追溯到一项工作；每段旅程都属于一种用户画像 × 一项工作；状态合法。
2. **质量：**JTBD 陈述包含情境／动机／结果（不含功能）；故事符合 INVEST 原则；验收标准可观察；旅程的所有层次均已填写。
3. **覆盖率：**每种用户画像至少有 1 项工作；每项工作至少有 1 段旅程和 1 个故事；每个 must／should 故事在 scenarios.md 中至少有 1 个场景（或明确标记为等待场景）。
4. 以逐项清单形式报告，并针对每项提出修正；应用已批准的修正。

完成定义

• 各层保持一致，ID 稳定，假设均已标明。
• 用户已批准新增或更改的条目。
• 已识别级联更新，并向下游交接（受影响的流程交给 ux-flows，受影响的场景交给 ux-scenarios）——整个链路绝不悄然偏移。
• 提供下一层：故事准备就绪 → ux-flows 会在任何 UI 工作开始前将其转化为用户流程。

references/ 中还有什么。 此技能直接提及 8 个契约；references/ 中共有 14 个，因为此技能提及的契约还会链接其他契约，完整依赖集合会随技能一并打包——skills CLI 只安装一个目录，否则同级目录中的文件就会失去依赖。打开此处提及的文件；其余文件会在某个契约指引你时，按名称从相关文件中找到。