flow-checker

[toolbox.get_flow]
description = "Fetch a specific flow checklist by ID. Returns preflight questions, postflight checks, key principles, and common smells. Flow IDs: onboarding, forms, pricing, dashboard, empty-states."
command = "curl"
args = ["-s", "-H", "Authorization: Bearer ${UXUI_API_KEY}", "https://uxuiprinciples.com/api/v1/flows?id={flow_id}"]

[toolbox.list_flows]
description = "List all available flow checklists with their IDs, metric targets, and common smell associations."
command = "curl"
args = ["-s", "-H", "Authorization: Bearer ${UXUI_API_KEY}", "https://uxuiprinciples.com/api/v1/flows"]

此技能的作用

你可以根据用户流程描述，执行分为两个阶段的清单审查。设计前：提出动手设计工具之前必须回答的问题。发布前：验证设计好的流程是否通过质量门槛。

流程审查并非针对屏幕级别，而是评估路径及影响路径的决策。请将此技能与 uxui-evaluator（屏幕级别）和 interface-auditor（异味检测）结合使用，以实现全面覆盖。

此技能需要 pro API 密钥。 如果没有密钥，你只能根据内部知识运行清单，并注明这一限制。内部知识涵盖相同的清单项目，但缺少实时异味关联和严重性元数据。

流程分类

共有五种流程，每种流程都针对特定的产品指标：

流程 ID	名称	目标指标	主要关注点
onboarding	新手引导	激活	首次使用体验、账户设置
forms	表单	完成率	数据收集、输入验证
pricing	定价	转化	套餐比较、购买决策
dashboard	仪表盘	留存	数据展示、任务完成
empty-states	空状态	激活	零数据状态、首次运行体验

清单结构

每种流程分为两个阶段：

预检（设计前）：用于揭示设计约束的策略性问题。这些不是 UI 检查项，而是用于揭示那些如果悬而未决就会导致重新设计的决策。确定布局之前，请回答所有问题。

后检（发布前）：二元验证项。每项都对应一个 UX 异味，并带有严重性。发布前必须通过 critical 项。high 项应当通过。medium 和 low 项则是改进机会。

审查工作流

步骤 1：识别流程类型

将用户的描述与五种流程 ID 之一匹配。如果描述涵盖多种流程（例如，以仪表盘结束的多步骤新手引导），请选择主要流程，并在 flow_note 中注明次要流程。

如果没有匹配的流程，请回复：“这不符合五种流程类型中的任何一种（onboarding、forms、pricing、dashboard、empty-states）。哪一种最接近？”

步骤 2：获取流程数据（如果已设置 API 密钥）

使用匹配的流程 ID 调用 get_flow。解析响应并提取：

• preflight.items：问题 + 原因 + 关联原则
• postflight.items：检查项 + 异味 + 严重性

如果 API 调用返回 401 或 403（没有密钥或使用免费版），请继续使用内部知识。设置 api_enriched: false，并在输出中添加升级说明。

步骤 3：运行预检

针对每个预检问题，判断提供的描述是否回答了该问题。

每个问题有三种状态：

• answered：描述提供了明确答案。引用相关部分。
• unanswered：描述中没有相关信息。这是在设计前需要补充的信息。
• partial：已有答案，但不完整或含糊不清。

步骤 4：运行后检

只有在提供了设计描述时才适用后检（不适用于仅描述设计意图的情况）。

针对每个检查项，评估其状态：pass、fail 或 unknown（描述没有提供足够的信息）。

将每项失败映射到其异味 ID 和严重性。任何一项 critical 失败都会阻止发布。

步骤 5：输出 JSON

严格按照以下结构返回。不要添加任何说明文字。

{
  "flow_id": "onboarding",
  "flow_name": "Onboarding",
  "flow_note": "string or null",
  "metric_target": "activation",
  "phase": "preflight|postflight|both",
  "preflight": {
    "summary": "X of Y questions answered.",
    "items": [
      {
        "id": "pf-1",
        "question": "What's the ONE thing users must accomplish?",
        "why": "Focus on single critical action, not everything at once.",
        "linked_principle": "cognitive-load",
        "status": "answered|unanswered|partial",
        "evidence": "Quote from description or null.",
        "recommendation": "Specific action if unanswered or partial, null if answered."
      }
    ],
    "gaps": ["pf-1", "pf-3"]
  },
  "postflight": {
    "summary": "X of Y checks passing. Y critical failures.",
    "ship_ready": true,
    "items": [
      {
        "id": "po-1",
        "check": "Progress indicator visible at all steps.",
        "linked_smell": "mystery-navigation",
        "severity": "critical|high|medium|low",
        "status": "pass|fail|unknown",
        "evidence": "Quote from description or null.",
        "recommendation": "Specific fix if failing, null if passing."
      }
    ],
    "critical_failures": ["po-1"],
    "high_failures": ["po-3"]
  },
  "key_principles": ["progressive-disclosure", "cognitive-load"],
  "common_smells": ["form-graveyard", "mystery-navigation"],
  "api_enriched": true,
  "api_note": "null or 'Flow checklists require a pro API key for live smell linkage and severity metadata. See uxuiprinciples.com/en/checkout'"
}

如果任何 critical 后检项目的 status: fail，则 ship_ready 为 false。只有所有 critical 项都通过时，ship_ready 才为 true。

phase 反映评估的内容：如果只描述了设计意图，则为 preflight；如果描述了已完成的设计，则为 postflight；如果两个阶段都可以评估，则为 both。

严重性参考（后置检查）

严重性	含义	发布门槛
critical	阻碍任务完成或导致数据丢失	发布前必须修复
high	显著降低体验	发布前应修复
medium	影响指标，但不影响核心任务	在下一次迭代中修复
low	外观或润色方面的改进	纳入待办列表

边界情况

尚无设计，只有意图： 仅运行前置检查。设置 phase: preflight。完全跳过后置检查区块（不要将项目设为 unknown）。

描述了设计，但未提及流程意图： 根据描述推断流程类型。在 flow_note 中说明你的推断。继续处理。

一个流程中包含多种流程类型（例如，仪表板中的空状态）： 选择占主导地位的流程。在 flow_note 中注明次要流程。运行主导流程的检查清单。

前置检查项目的回答不明显： 标记为 answered，并在 evidence 中解释你的判断依据。不要低估描述提供的信息。

API 返回 403（免费套餐）： 流程仅限专业版使用。设置 api_enriched: false。根据内部知识继续完成所有检查清单项目。添加："api_note": "Flow checklists require a pro API key. See uxuiprinciples.com/en/checkout"。

描述非常简短（“我正在构建一个注册表单”）： 仅运行前置检查。将所有项目设为 unanswered，并给出建议。返回 phase: preflight。

示例

示例 1：入门流程前置检查

输入：

We're designing a new user onboarding for our SaaS app. Users sign up, verify email, then get dropped into an empty dashboard. We're not sure how many steps to use.

预期输出结构：

{
  "flow_id": "onboarding",
  "flow_name": "Onboarding",
  "flow_note": "Empty dashboard at end suggests empty-states flow also applies.",
  "metric_target": "activation",
  "phase": "preflight",
  "preflight": {
    "summary": "1 of 5 questions answered.",
    "items": [
      {
        "id": "pf-1",
        "question": "What's the ONE thing users must accomplish?",
        "why": "Focus on single critical action, not everything at once.",
        "linked_principle": "cognitive-load",
        "status": "unanswered",
        "evidence": null,
        "recommendation": "Define the single activation event before designing steps. Is it connecting a data source? Inviting a teammate? Creating a first item?"
      },
      {
        "id": "pf-5",
        "question": "What happens if they abandon halfway?",
        "why": "Allow resume without data loss to reduce frustration.",
        "linked_principle": "error-prevention",
        "status": "unanswered",
        "evidence": null,
        "recommendation": "Decide whether onboarding state is saved server-side so users can resume after email verification gap."
      }
    ],
    "gaps": ["pf-1", "pf-3", "pf-4", "pf-5"]
  },
  "postflight": null,
  "key_principles": ["progressive-disclosure", "cognitive-load", "fitts-law"],
  "common_smells": ["form-graveyard", "mystery-navigation", "silent-errors"],
  "api_enriched": true,
  "api_note": null
}

示例 2：表单后置检查

输入：

Registration form: 6 fields (name, email, password, company, role, team size). All required. Shown on one page. Submit button at the bottom. Error messages appear in a red banner at the top after clicking submit. No inline validation.

预期输出结构：

{
  "flow_id": "forms",
  "flow_name": "Forms",
  "flow_note": null,
  "metric_target": "completion-rate",
  "phase": "postflight",
  "preflight": null,
  "postflight": {
    "summary": "4 of 8 checks passing. 2 critical failures.",
    "ship_ready": false,
    "items": [
      {
        "id": "po-3",
        "check": "Error messages appear next to problematic fields.",
        "linked_smell": "silent-errors",
        "severity": "critical",
        "status": "fail",
        "evidence": "Error messages appear in a red banner at the top after submit.",
        "recommendation": "Move error messages inline, directly below each problematic field. Banner errors require users to scroll back and locate the field causing the error."
      },
      {
        "id": "po-5",
        "check": "Submit button disabled until valid (or shows clear errors).",
        "linked_smell": "silent-errors",
        "severity": "medium",
        "status": "fail",
        "evidence": "No inline validation mentioned.",
        "recommendation": "Add inline validation on field blur. At minimum, show password strength indicator as user types."
      }
    ],
    "critical_failures": ["po-3"],
    "high_failures": []
  },
  "key_principles": ["cognitive-load", "error-prevention-in-forms"],
  "common_smells": ["form-graveyard", "silent-errors"],
  "api_enriched": true,
  "api_note": null
}

完成标准

满足以下条件时，输出即为完整：

1. flow_id 与五个有效 ID 之一匹配
2. phase 准确反映已评估的内容
3. 每个前置检查项目的状态均为以下之一：answered、unanswered、partial
4. 每个后置检查项目的状态均为以下之一：pass、fail、unknown
5. 如果任何严重性为 critical 的后置检查项目的 status: fail，则 ship_ready 为 false
6. gaps 仅列出 status 为 unanswered 或 partial 的 ID
7. critical_failures 仅列出 severity: critical 且 status: fail 的 ID
8. api_enriched 准确反映工具箱调用是否返回 200
9. 输出为有效 JSON，前后均无说明文字