ux-flows

ux-flows — 使用フローのカタログ化とオーケストレーション

このスキルは、プロジェクトの使用フローに関する信頼できる唯一の情報源であり、それらをペルソナに引き渡す指揮役でもあります。プロジェクトデータであるフロー（何をするか）と、ux-persona スキルにあるユーザビリティのウォークスルー（どのようにするか）を分離しています。スタックに依存せず、ポートやアドレスをハードコードせず、各フローが独自のエントリーポイントを宣言します。

フローの保存場所

規約：プロジェクト内の e2e/flows/<id>.md に、フローごとに1つのファイルを作成し、バージョン管理します。テンプレート：

---
id: <kebab-id>
name: <readable name>
reference: <optional: requirement / ticket>
persona: <id of e2e/personas/<persona>.md, or a bundled ux-persona persona>
entry: "<entry-point URL — typically the app's home/landing>"
preconditions:
  - <app running at the entry point>
  - <minimal data required>
design_refs:               # optional but recommended: the planned design per screen
  <screen-key>: "<Figma node URL / exported image / spec — the source of truth for that screen>"
---

## User goal
<what the person wants to achieve, in one sentence>

## Steps (each step is a UI ACTION + the expected result)
1. At the entry point (`<screen-key>`), **<UI action>** → <expected result>.
2. (`<screen-key>`) **<UI action>** → <expected result>.

## Expected result
<the final observable state that proves success>

モデリングルール： すべてのフローはエントリーポイント（ホーム／ランディング）から開始し、UI 操作（クリック／入力）を記述します。「URL X に移動する」とは記述しません。これにより、ペルソナはナビゲーションでは到達できない画面を指摘できます。画面に予定されているデザインがある場合は、design_refs に記載してください。そうすることで、ペルソナはユーザビリティだけでなく、実装された画面とプロトタイプのデザイン忠実度も検証できます。

コマンド（$ARGUMENTS 経由）

• 空または list → プロジェクトのフロー（id · 名前 · ペルソナ · 参照）を一覧表示し、実行するかどうかを尋ねます。カタログが空または存在しない場合は、まず discover を実行します（以下を参照）。「フローがありません」と報告するだけで終わらせてはいけません。
• <flow-id> → 1つのフローを実行します。フローファイルのパスを指定して ux-persona スキルを呼び出します。
• all → すべてのフローを順番に実行します（ブラウザーは1つのリソースなので、並列実行してはいけません）。各フローについて ux-persona を呼び出し、次のフローに進む前にレポートを待ちます。カタログが空の場合は、まず discover を実行し（ドラフトを確認してから）、その後に実行します。
• new → 1つのフローの作成を支援します。ゴール／ペルソナ／参照について尋ね、エントリーポイントと実際の UI 手順を特定し（必要に応じてプロジェクトのルート／画面を調査）、上記のテンプレートを使って e2e/flows/<id>.md を作成します。
• discover → フローがまだない場合に、アプリケーションを調査してカタログを作成します（以下のディスカバリーを参照）。

ディスカバリー — 空のカタログの初期設定

カタログでは e2e/flows/ 規約を前提としていますが、何もない状態から始めるプロジェクトもあります。フローがない場合（またはユーザーが discover を求めた場合）は、自分でアプリを調査し、初期カタログを提案します。ユーザーにゼロから作成させてはいけません。スタックに依存しないよう、利用可能な手掛かりを組み合わせます。

1. 画面／ルートを把握する。 コードベースでルーター（ルート定義、routes/／pages/／app/ ディレクトリ、サイトマップ、ルートマニフェストなど）を調べ、到達可能な画面とエントリーポイント（ホーム／ランディング）を列挙します。フレームワークによって異なるため、1つの仕組みを前提にせず、プロジェクトのルーティング機構を探します。
2. ナビゲーションを確認する。 エントリーポイントから（実行中のアプリ、またはランディングコンポーネントで）、ユーザーに実際に提示されている操作を確認します。これにより、到達可能なユーザージャーニーと孤立した画面を区別できます。
3. 意図を読み取る。 プロダクト／要件ドキュメント、README、ルート／画面の名前、主要な CTA から、ユーザーのゴール（例：「登録する」「検索してアイテムを表示する」「注文の状況を確認する」「購入を完了する」）を推測します。1つのゴールにつき1つのフローを作成します。
4. ペルソナごとに分類する。 各フローに適切なペルソナ（組み込みのもの、またはプロジェクト独自のもの）を割り当てます。異なる利用者層（エンドユーザーとバックオフィス／管理者など）には、通常、別々のペルソナが適しています。
5. カタログのドラフトを作成する。 テンプレートを使い、各ゴールにつき1つの e2e/flows/<id>.md を作成します。手順は、エントリーポイントからのUI 操作として記述します。必要に応じて e2e/personas/<id>.md も作成します。
6. 実行前に確認する。 提案するフロー（id · 名前 · ペルソナ · エントリー · 手順数）を提示し、ユーザーに確認、削除、修正してもらいます。ディスカバリーで提案し、カタログの所有者はユーザーです。

ディスカバリーは可能な限りの調査です。コードだけではフローの UI 経路が明確でない場合は、ドラフトに前提を記載し、ペルソナの実行時に（そして人間が）確認または反証できるようにします。調査済みで未確認のフローでも、カタログがないよりは有用です。

オーケストレーション（実行 ＝ ペルソナにディスパッチ）

1. 事前チェックは 1 回だけ： アプリはフローの開始地点で実行されていますか？ 実行されていない場合は、プロジェクトの実行コマンドで起動するか、状況を報告して停止します。最小限のデータは投入されていますか？
2. 選択した各フローについて、フローファイルのパスを指定して ux-persona スキルを呼び出します。 順番に実行し、次に進む前にレポートを待ちます。
3. 最後に、今回作成されたレポート（e2e/usability/）を読み、スコアボードを作成します。フローごとの判定と重大度別の指摘件数をまとめ、さらに各項目の画面／参照先を示した優先順位付きのユーザビリティ修正リスト（ブロッカーを最優先）を作成します。

Webwright を使用した実行

ユーザーが Webwright、再生可能なエビデンス、生成されたブラウザースクリプト、またはより詳細なスクリーンショット／操作ログを求めた場合も、このスキルをカタログのオーケストレーターとして維持し、各フローを引き続き ux-persona にディスパッチします。該当フローの実行バックエンドとして Webwright を使用するよう、ux-persona に指示してください。

e2e/flows/*.md を Webwright スクリプトに置き換えないでください。フローの定義は引き続き信頼できる情報源です。Webwright の final_runs/run_<id>/ 成果物は、生成された e2e/usability/<flow-id>--<date>.md レポートを補足するエビデンスです。永続的な CI 回帰テストには、引き続きネイティブの Playwright E2E を使用します。

カタログのメンテナンス

• 新しいジャーニー／画面が追加されたら、対応する e2e/flows/<id>.md を作成します。
• ユーザビリティ修正を行ったら、指摘が解消されたことを確認するため、影響を受けるフローを再実行します（UX 回帰テスト）。
• e2e/usability/ のレポートは履歴です。削除せず、実行のたびに新しい日付付きレポートを作成してください。

推奨されるプロジェクト構成

e2e/
  personas/<persona>.md      # reusable project personas (the persona's lens)
  flows/<id>.md              # one file per flow (the definition handed to the persona)
  usability/<id>--<date>.md  # findings reports (generated by runs)

ペルソナには、ux-persona スキルに同梱されている一般的なもの（novice、rushed、skeptical、mobile、accessibility、power-user）も使用できます。