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"]

このスキルでできること

ユーザーフローの説明を対象に、2段階のチェックリスト監査を実施します。デザイン前には、ツールに着手する前に答えるべき質問を明らかにします。リリース前には、設計したフローが品質基準を満たしているか確認します。

フロー監査は画面単位ではありません。フローの経路と、それを形作る意思決定を評価します。全体を網羅するには、このスキルを uxui-evaluator（画面単位）および interface-auditor（問題点の検出）と併用してください。

このスキルには Pro API キーが必要です。 キーがない場合は、内部知識のみでチェックリストを実行し、その制約を明記します。内部知識は同じチェック項目を網羅していますが、リアルタイムの問題点との関連付けや重大度のメタデータはありません。

フローの分類

5つのフローがあり、それぞれ特定のプロダクト指標を対象としています。

Flow ID	名前	指標の対象	主な懸念事項
onboarding	オンボーディング	アクティベーション	初回利用時の体験、アカウント設定
forms	フォーム	完了率	データ収集、入力検証
pricing	価格設定	コンバージョン	プラン比較、購入の意思決定
dashboard	ダッシュボード	継続率	データ表示、タスク完了
empty-states	空の状態	アクティベーション	データがない状態、初回利用時の体験

チェックリストの構成

各フローには2つのフェーズがあります。

Preflight（デザイン前）：デザイン上の制約を明らかにする戦略的な質問です。UI のチェックではありません。未回答のままにすると再設計につながる意思決定を明らかにします。レイアウトを決定する前に、すべてに回答してください。

Postflight（リリース前）：二択で検証する項目です。それぞれが UX の問題点と重大度に対応しています。リリース前に critical の項目をすべて通過する必要があります。high の項目も通過させるべきです。medium と low は改善の機会です。

監査ワークフロー

ステップ 1：フローの種類を特定する

ユーザーの説明を5つのフロー ID のいずれかに対応付けます。説明が複数のフローにまたがる場合（たとえば、ダッシュボードで終わる複数ステップのオンボーディング）は、中心となるフローを選び、二次的なフローを flow_note に記載します。

該当するフローがない場合は、次のように回答します。「これは5つのフローの種類（onboarding、forms、pricing、dashboard、empty-states）のいずれにも該当しません。最も近いものはどれですか？」

ステップ 2：フローデータを取得する（API キーが設定されている場合）

該当するフロー ID を指定して get_flow を呼び出します。レスポンスを解析して、次の項目を抽出します。

• preflight.items：質問 + 理由 + 関連する原則
• postflight.items：チェック項目 + 問題点 + 重大度

API 呼び出しで 401 または 403 が返された場合（キーがない、または無料プランの場合）は、内部知識を使って続行します。api_enriched: false を設定し、出力にアップグレードに関する注記を追加します。

ステップ 3：Preflight を実行する

各 Preflight の質問について、提示された説明で回答されているかを評価します。

各質問を次の3つの状態に分類します。

• answered：説明に明確な回答があります。関連する箇所を引用します。
• unanswered：説明に情報がありません。これはデザイン前に解消すべき不足事項です。
• partial：回答はありますが、不完全または曖昧です。

ステップ 4：Postflight を実行する

Postflight はデザインの説明が提示されている場合にのみ適用されます（意図のみの場合は適用されません）。

各チェック項目を pass、fail、unknown（説明の情報が不十分）で評価します。

失敗をそれぞれの問題点 ID と重大度に対応付けます。critical の失敗が1つでもあると、リリースはできません。

ステップ 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'"
}

ship_ready は、critical の Postflight 項目に status: fail が1つでもある場合、false です。すべての critical 項目を通過した場合にのみ true です。

phase は評価した内容を示します。デザインの意図のみが説明されている場合は preflight、完成したデザインが説明されている場合は postflight、両方のフェーズを評価できる場合は both です。

重大度の基準（ポストフライト）

重大度	意味	リリース基準
critical	タスクの完了を妨げる、またはデータ損失を引き起こす	リリース前に必ず修正する
high	エクスペリエンスを大幅に損なう	リリース前に修正することが望ましい
medium	指標に影響するが、主要なタスクには影響しない	次回のイテレーションで修正する
low	見た目や仕上がりの改善	バックログに追加する

エッジケース

デザインはまだなく、意図のみがある： プリフライトのみを実行します。phase: preflight を設定します。ポストフライトのブロックは完全に省略します（項目を unknown に設定しないでください）。

デザインの説明はあるが、フローの意図に言及がない： 説明からフローの種類を推測します。推測内容を flow_note に追加して、続行します。

1つのフローに複数のフロータイプが含まれる（例：ダッシュボード内の空の状態）： 主要なフローを選びます。副次的なフローを 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 が5つの有効な 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 が、toolbox の呼び出しで 200 が返されたかどうかを正確に反映している
9. 出力が有効な JSON であり、その前後に文章がない