reviewing-user-flows

reviewing-user-flows — SKILL.md

バリアント： standard · 使用する場面： 完成したユーザーフロー文書を受け入れゲートとして評価するとき — 完全性、たどりやすさ、構造、回復力、アクセシビリティ、妥当性を確認し、実行可能な指摘とともに VERDICT: approve|revise を出力します。

概要

このスキルは、ユーザーフローを作成する側と評価する側のペアのうち、レビューを担います。完成したユーザーフロー文書を手にしたレビュアーが読み込み、次の問いに照らしてその文書を評価します。後続のワイヤーフレーム作成工程で、すべての画面を列挙できますか。また、すべての経路をたどり、復旧し、完了できますか（AT ユーザーによる完了も含みます）。そして、そのフローは適切ですか。 ユーザーフロー文書はナビゲーションとインタラクションのグラフを示します。つまり、入口と IA の枠組み、正常系の経路、判断分岐、エラー／復旧とエッジ状態、インタラクションの回復力、フローレベルのアクセシビリティ、そして経由する画面と状態です。このスキルは固定のチェックリストを適用します（ユーザーフロー作成者が目指す基準と同じなので、作成基準とレビュー基準がずれることはありません）。そのうえで、機械的に解析できる単一の判定と、作成者が一度の修正で対応できる指摘を出力します。これは受け入れゲートです。フローを作成、修正、描き直すことはせず、評価して指摘を返します。

有効化する場面

• 完成したユーザーフロー文書について、後続のワイヤーフレーム作成を始める前に受け入れ／修正の判断が必要なとき。
• 作成者が作成したユーザーフロー文書を、独立したレビュアー／ゲートキーパーとして確認するとき。
• 以前の判定が revise だったユーザーフロー文書の修正版を再評価するとき。
• 修正内容を評価するとき — 以前のユーザーフロー文書に対するバージョン管理された差分（差分に範囲を限定したレビュー、条件 13）。

次の場合は有効化しないでください：

• ユーザーフロー文書の作成または修復 → authoring-user-flows を使用してください。このスキルはフローを作成しません。
• 画面のレイアウト／構造（領域の配置、コンテンツの階層、画面ごとのコンポーネント）または画面単位のピクセルレベルのアクセシビリティ（コントラスト、ターゲットサイズ、フォーカスの見え方）をレビューするとき → それはワイヤーフレームレビュー用スキルの対象です。このゲートが評価するのは画面のつながり方と各経路を完了できるかであり、画面の見た目ではありません。
• 上流の PRD（目標、ペルソナ、指標）をレビューするとき → PRD レビュー用スキルを使用してください。
• テンプレート／セクションへの準拠を確認するとき → それはテンプレートに関する内容です。このスキルが評価するのは基準に照らした品質であり、すべての見出しがそろっているかどうかではありません。
• ユーザージャーニー（感情／チャネル／時間経過）を評価するとき — 別の成果物です。

ワークフロー

ステップ 1：新鮮で独立した視点で文書全体を読む

初めて読むかのように、ユーザーフロー文書を最初から最後まで読みます。上流の PRD（目標とペルソナ）も並べて参照します。網羅性はそれらの目標に照らして評価します。デザインシステム（提供されている場合）はナビゲーション／コンポーネントの参照情報として手元に置きます。修正内容を評価する場合は、以前のバージョンも手元に置きます。次の工程（ワイヤーフレーム作成）と、実際にこれらの経路をたどるユーザーにとってのゲートキーパーとして臨みます。画面を列挙できない、経路をたどれない／復旧できない／完了できない、取り消せない操作に保護がない、または必要なタスクに対してフローが客観的に劣っていることを示す場合、その指摘には重みがあります。フロー、分岐、終了、引き継ぎのうち、どれが重要な役割を担っているかに注意します。

ステップ 2：チェックリストを実施する — 各条件を合格／不足で判定する

以下の各条件について、合格または不足を判定します。条件が不合格となるのは、実際に存在し、具体的に特定できる欠陥がある場合に限られます。「自分なら違う描き方をする」は不足ではありません（品質に関する条件は客観的なものに限ります。条件 12 を参照）。不足がある場合は、正確な箇所（フロー、ステップ、分岐、ノード、引き継ぎ）と欠けている内容を記録します（ステップ 4 で実行可能な指摘にします）。条件の適用度はプロダクトに応じて変わります（「比例性」を参照）。

以下の能力境界に関するチェック項目は、作成時の呼び出しに capability_record が注入され、レビュー時のコンテキストとして利用できる場合にのみ適用されます。存在しない場合は該当なしとして扱います。境界が定義されていないのに、能力境界のマーカーがないことを理由に文書を減点してはいけません。 維持する中核項目（網羅性＋たどりやすさ）：

1. 目標／ペルソナの網羅 — 孤立項目なし。 PRD の各目標（ペルソナが達成しようとしていることとして定義）がフローに対応し、各フローが目標／ペルソナに結び付いていること。標準的なフローは確立されたパターンに基づいている（または逸脱の理由が明記されている）こと。網羅性マップがあること。目標にフローがない、フローがどの目標にも対応していない、網羅性マップがない、または解決済みの問題に対するフローを理由なく再発明している場合は、ギャップです。
2. 明確な開始点＋終了点。 各フローで、すべての開始点（ホームページ、ディープリンク、メール、通知 — それぞれ異なる状態から開始する場合があります）と、具体的な成功／確認状態（抽象的な「成功」だけではない）を明示すること。別の終了方法（キャンセル／中断／引き継ぎ）が適切に処理されていること。フローが途中から始まっている、または具体的な終了状態がない場合は、ギャップです。(省略しない基本要件：すべてのフローに成功状態があること。)
3. すべての判断分岐が解決済み。 各判断で、すべての分岐先を列挙し、それぞれをステップ、別のフロー、または終了点に結び付けること。行き先のない分岐や、どこにもつながっていない分岐があれば、ギャップです。
4. すべてのエラー／エッジ状態に復帰手段がある — 行き止まりなし。 該当する場合、空／null、無効な入力、タイムアウト／ネットワーク／インテグレーション、中断／セッション消失、権限／認証、戻る／キャンセルのそれぞれを、生産的なステップに戻すこと。さらに、すべての非同期ステップに読み込み中／処理中の状態と、成功／確認状態を設けること。ユーザーを行き止まりにしないこと。重要な状態では、メッセージの意図を明示すること — エラー＝原因＋修正方法、空＝次のアクションへの案内、成功＝結果。該当する状態が欠けている、エラーパスが行き止まりになっている、非同期ステップに読み込み状態がないまま成功へ進む、エラーからの復帰手段がない、または重要な状態で必要なメッセージの意図が指定されていない場合は、ギャップです。
5. ステップが明確で、たどりやすい。 読者が推測せずに説明を追えること。各ステップで画面／状態とユーザーの操作を明示すること。ラベルがあること。ステップが曖昧、またはノードにラベルがない場合は、ギャップです。
6. 両方の表記が一致している。 すべてのフローに Mermaid のフローチャートと、番号付きの説明＋分岐／エラーの一覧があり、同じグラフを表していること。複数のアクターが登場するフローではスイムレーンを使うこと。 一方の表記が欠けている、ノード／分岐が表記間で食い違っている、または複数のアクターが登場するフローで、誰が何をするのかが区別のないレーンに隠れている場合は、ギャップです。
7. ワイヤーフレーム作成に必要な画面を列挙できる。 画面一覧に、すべてのフローの画面／状態（読み込み中＋成功を含む）が漏れなく含まれていること。それぞれに正規の名前を1つ付け、図／説明／一覧のすべてで同じ名前を使い、孤立した項目を残さないこと。参照されている画面が一覧にない、名前が一致しない、一覧に孤立した項目がある、または一覧がない場合は、ギャップです。(省略しない基本要件：命名と一覧への網羅的な記載。)
8. 前提と未解決の質問を明示する；フローとジャーニーを混同しない。 PRD の情報が少ない場合は前提を明示し（異議を唱えられるようにする）、未解決の質問を列挙し、プロダクトに関する判断を暗黙のままにしないこと。ドキュメントはインタラクショングラフにとどめること（ステップごとの感情／チャネルは含めない）。判断が埋もれている、またはジャーニーの内容がフローの一部として示されている場合は、ギャップです。(省略しない基本要件：フローとジャーニーの境界。)

新規項目（構造、レジリエンス、アクセシビリティ、品質、修正）： 9. ナビゲーションとIAの枠組み（該当する場合）。複数のサーフェスを持つ製品では、ナビゲーション／アプリシェルのモデルと経路案内が用意されています。ディープリンク（および前提条件のチェック／再開）と、デバイス間で経路が分岐する場合の対応が明記されています。フロー間の引き継ぎはすべて、定義済みのフローに到達し、孤立したフロー（到達できない、または遷移先がないフロー）はありません。削除済みまたは未定義のフローへの引き継ぎ、ナビゲーションモデルを無視する複数サーフェス製品のフロー、または実際のデバイス間の差異は、ギャップです。対象外： 単一画面／単一フローのツールには、アプリシェルもフロー間のグラフもなく、入口が一つです。これはギャップではありません。 10. インタラクションの回復性（該当する場合）。取り消し不能または破壊的な操作にはすべて、確認または取り消しが用意されています。複数ステップの各フローでは、中断後に再開するか、最初からやり直すかが明記されています。状態を変更するステップでは、変更内容が示されます。楽観的な操作には、取り消しとフィードバックの経路が定義されており、支払い／削除には使われていません。ガードされていない取り消し不能な操作、通知されない状態変更、中断時の動作が明記されていない長いフロー、安全でない、または取り消し手段のない楽観的な操作は、ギャップです。対象外： 読み取り専用のフローには、ガード、保持、確認が必要なものはありません。これはギャップではありません。 11. フローレベルのアクセシビリティ。 すべての経路をキーボードで完了でき（トラップがない）、支援技術（AT）でも完了できます（エラーが通知され、色や位置だけに依存しません）。ステップ／ルートの変更時にはフォーカス順序が管理されています（WCAG 2.2 SC 2.4.3）。必須ステップがマウスのみ／ジェスチャーのみで操作するものではありません。必須ステップがマウスのみである、AT の利用者が行き詰まるほどエラーが視覚的にしか認識できない、またはステップ変更時にフォーカスが管理されていない場合は、ギャップです。(縮小されない基準：キーボードで操作できること。単一画面のフローではステップ間のフォーカスに関する懸念は軽減されますが、経路は引き続きキーボード／AT で完了できなければなりません。) 画面ごとのピクセル単位の WCAG（コントラスト／ターゲットサイズ）は、ここでは対象外です。これはワイヤーフレーム／DS の範囲です。 12. フローの品質（客観的な評価のみ）。 不必要なステップはありません（経路はタスクの遂行に必要な長さを超えず、経路の長さはここで一度だけ評価します）。取り消し不能な操作は、実行後に回復するだけでなく、実行前に防止されています。前のステップで確定した内容を引き継がずに思い出すことを求めるステップはありません。同種のタスクには一貫した経路が用意されています。理由のない実質的に長すぎる経路、防止されていない取り消し不能な操作、ステップをまたいだ想起の負担、または類似フロー間の正当な理由のない不整合は、ギャップです。主観的な好みはギャップではありません。「もっと良いフローがある」という理由だけで修正を求めることはありません。対象外： 簡単なフローは、その簡潔さによって基準を満たします。 13. 差分に限定したレビュー（改訂を評価する場合のみ）。ドキュメント全体ではなく、差分とその波及範囲をレビューします。変更されていないフローはそのままです（範囲外の再生成はしません）。フロー間の引き継ぎが、削除または改名されたフローを参照していません。画面インデックスに孤立した項目や不足項目はありません。以前到達可能だった経路が新たに行き止まりになっていません。編集箇所で図と説明文が同期しています。ドキュメントのバージョン更新が変更の種類に合致しています（フローの削除／改名または到達可能な経路の削除は MAJOR、追加は MINOR、文言変更は PATCH）。変更履歴が差分と一致しています。破壊的な削除には非推奨化の案内があります。これらのいずれかに問題があれば、ギャップです。対象外： 新規プロジェクトの初回構築では、この条件は適用されません。 14. 機能ルーティング（機能レコードがない場合は該当しません）：機能をまたぐ各遷移では、遷移元と遷移先の機能 ID が明示されています。entry_point／exit_point のラベルは機能レコードと一致しています。

ステップ 3：判定を決める

• approve — 該当するすべての条件を満たしています。ワイヤーフレームレビューで、すべての画面を列挙し、すべてのパスをたどれます。記載どおり、パスを再現でき、堅牢で、完了可能であり（AT ユーザーを含む）、客観的に妥当です。スタイル面で改善できると思えても、承認してください。基準はチェックリストであり、完璧さではありません。
• revise — 1 つ以上の条件に、実際に特定できる不足があります（孤立した目標、開始地点のないフロー、未接続の分岐、行き止まりになるエラーパス、ローディング／成功状態の欠落、保護されていない取り消し不能な操作、マウス操作のみの必須ステップ、AT ユーザーが先に進めないエラー、不必要に長いパス、削除済みフローへの引き継ぎ、図と説明の不整合、インデックスにない画面、バージョンを誤った修正など）。

努力を示すため、あるいはあると望ましい機能を求めるために修正を要求してはいけません。主観的な好みを理由にすることも避けてください。条件は満たしているか、満たしていないかのどちらかです。

ステップ 4：判定と実行可能な指摘を出力する

判定は、単独の行に VERDICT: approve または VERDICT: revise という文字列をそのまま出力します。前後にコードフェンス、引用符、その他の語句を付けてはいけません（ここでのフェンスは説明用にすぎません）。

VERDICT: approve

続けて指摘を列挙します。revise の場合、各指摘は実行可能でなければなりません。つまり、不合格となった条件、正確な場所、そして修正方法を示し、作成者が一度の作業で解決できるようにします。approve の場合、指摘は任意であり、承認を妨げない内容に限ります。

良い指摘は、不足点と修正方法を明示します。

revise — 堅牢性（条件 10）：Flow 3（アカウント設定）では、「アカウントを削除」ボタンから確認や取り消しのステップなしに、成功状態へ直接進みます。修正方法：取り消し不能な削除の前に確認ステップを追加する（または、取り消し可能な論理削除と復元操作を用意する）とともに、削除された内容を表示してください。

revise — フローのアクセシビリティ（条件 11）：Flow 2（オンボーディング）の「優先順位を並べ替える」ステップはドラッグ操作のみで、キーボードによる代替手段がないため、キーボード／AT ユーザーはパスを完了できません。修正方法：キーボードで操作できる並べ替え（上へ／下へ移動するコントロール）を追加し、並べ替えた項目にフォーカスが移動するようにしてください。

悪い指摘は曖昧で、実行に移せません。

フローをもっと堅牢にできるはずです。 (どのフローですか？どの条件ですか？どう直せばよいですか？)

ルール

必ず守るルール（違反禁止）：

• 判定行は必ず1行だけ出力し、VERDICT: approve または VERDICT: revise とする — 文字列はそのまま、単独の行に記載し、ほかの内容を含めないでください。後続のツールがこの行を解析します。
• 作成者ではなく、審査者として判断してください。 指摘事項を返し、フローを書き直したり、修正したり、補完したりしないでください。
• 単一の基準に従ってください。 ステップ2の14項目に照らして判断してください。これは作成者が目指す基準と同じです。独自の項目や、より厳しい独自基準を追加しないでください。特に、条件12は客観的な項目のみです。主観的な好みは指摘事項になりません。
• 誤った「revise」判定を避けてください。 適用されるすべての条件を満たすドキュメントは、シンプルな製品向けの小規模なものであっても承認してください。実際に存在する、具体的に名前を挙げられる問題がある場合に限り、修正を求めてください。新しい条件（9〜13）はそれぞれ、薄いアーキタイプでは対象外となり得ます（「比例性」を参照）。適用されないセクションを正当に省略した薄いフローに対し、問題をでっち上げないでください。
• 誤った「approve」判定も避けてください。 実際の問題がある場合は、決して承認しないでください。行き止まりの経路、目標の孤立、確認や取り消し手段のない不可逆な操作、AT で抜け出せないエラー、インデックスにない画面、削除済みのフローへの引き継ぎは、すべて revise にしてください。
• 行き止まりと、保護されていない不可逆な操作は、承認を妨げる問題です。 ユーザーが先へ進めなくなる経路、または確認や取り消し手段のない不可逆な操作がある場合は、必ず revise にしてください。
• F5/F6 の境界。 画面ごとのピクセル単位の WCAG（コントラスト／ターゲットサイズ／フォーカス表示）はワイヤーフレーム／DS の対象であり、条件11の対象ではありません。経路の長さは条件12で一度だけ評価し、条件11では再評価しないでください。
• ドキュメントに提示された上流成果物に照らして判断してください。 ドキュメントの depends_on セットを基準に評価してください。未作成の上流成果物は、決して revise の理由にはなりません。参照すべき作成済みの上流成果物を無視したドキュメントについては、妥当な指摘事項になります。
• すべての revise 指摘は、具体的な対応につながるものにしてください — 未達の条件、該当箇所、具体的な修正方法を示してください。

推奨事項（必要に応じて変更可能）：

• 指摘事項は重大度順に並べてください — まず承認を妨げる問題（行き止まり、保護されていない不可逆な操作、孤立した目標、欠落した画面、AT で抜け出せないエラー）を挙げ、その後に軽微な問題を挙げてください。
• 作成者が基準と照合できるよう、各指摘で条件番号または条件名を明記してください。
• 該当箇所を示す際は、フロー名に加えて具体的なノード／ステップ／分岐／引き継ぎ箇所を明記してください。
• approve に添える注記は少数にとどめ、承認を妨げない内容であることを明確にしてください。

比例性

「ワイヤーフレーム作成に十分な品質で、たどることができ、堅牢で、アクセシブルで、妥当である」という基準は、製品に応じて変わります。シンプルな製品では、フローやエッジケースが少なく、アプリシェルやレジリエンスのセクションがなくても不自然ではありません。適用されるすべての条件を満たす、小規模で完全なドキュメントは合格です。薄いアーキタイプでは、新しい条件は対象外となる場合があります。9（アプリシェル／クロスフローグラフが不要な単一画面ツール）、10（読み取り専用フローで保護が必要なものがない場合）、11（単一画面フローではステップ間のフォーカス移動は少なくてよいものの、キーボード／AT で完了できることは依然必要）、12（自明なフローは自明に条件を満たす）、13（グリーンフィールドでは差分レビューが発生しない）。4つの条件は規模にかかわらず適用される基本条件です。どの規模でも満たさなければフローが破綻するためです。cond-2（具体的な成功状態）、cond-7（標準的な命名と画面の列挙）、cond-8（フローであり、ジャーニーではないこと）、cond-11（キーボード操作性）が該当します。フローの数ではなく、完全性と経路の品質を評価してください。短いことを理由に問題をでっち上げるのは、ここで最もよくある審査ミスです。

注意点

• ウォークスルー可能性／レジリエンスではなく、網羅性だけを基準に承認する。 すべてのフローが記載されていても、ドキュメントがウォークスルーできないことがあります。片側が欠けた分岐、復旧方法のないエラー、内容がずれていく図、ガードされていない削除、AT で行き詰まるエラーなどです。テンプレートが埋まっているかではなく、すべての経路をたどり、復旧し、完了でき、かつ健全であるかを判断してください。
• 行き止まり／ガードされていない不可逆操作を見落とす。 どちらも問題のある経路に潜んでいます。問題のない経路は常に完全に見えます。すべての分岐とエラーを終端まで追い、すべての不可逆操作についてガードを確認してください。
• 暗黙の状態変更／ローディング状態の欠落を見落とす。 「何が変わったか」の説明なしに状態を変更するステップや、成功へ飛躍する非同期ステップは、一見完全でも欠落があります（cond. 4/10）。
• 表記を一つしか確認しない。 図を読んで説明文を飛ばす（またはその逆をする）と、必然的に同期の不備を見落とします（cond. 6）。
• cond. 11 にピクセル単位の WCAG 基準を持ち込む。 コントラストやターゲットサイズはワイヤーフレーム／DS の対象であり、フローレベルの a11y ではありません。二重に評価しないでください。
• シンプルなプロダクトを誤って差し戻す。 薄いフローが、そのプロダクトに存在しないアプリシェル、レジリエンス、デバイス間の差異を適切に省略している場合があります。該当しないエッジ状態は欠落ではありません。新しい条件は集約されます。プロダクトの規模に合わせて調整してください。
• 好みを理由に差し戻す（cond. 12）。 「自分なら違うデザインにする」は、決して欠落ではありません。条件 12 は客観的な場合に限ります。
• 修正依頼でドキュメント全体を再評価する。 修正依頼の場合、レビュー対象は変更箇所とその波及部分に絞ってください（cond. 13）。変更されていないフローを蒸し返さないでください。
• 判定トークンのぶれ。 「Approved」、「LGTM」、「needs work」、または埋もれた判定では解析できません。独立した行に、文字どおり VERDICT: approve|revise と出力してください。

アンチパターン

• 中身を見ずに承認する。 問題のある経路、不可逆操作、または AT 経路を追跡せず、問題のない経路を流し読みして承認すること。
• 細部にこだわって差し戻す。 図のスタイル、ノードの形、言い回しを欠落に見せかけて問題にしたり、主観的な好みで差し戻したりすること。差し戻しは、具体的に特定された実際の阻害要因に限ります。
• 無断で描き直す。 レビュー中に作成まで行うと、作成と判定の分離が崩れます。
• 条件を勝手に追加する。 作成者が満たすよう求められていない独自の要件（各ステップでの「感情」、主観的な「より良いフロー」など）を加えると、レビュー基準が作成基準からずれてしまいます。
• レイアウト、ピクセル、目標を評価する。 ボタンの配置やコントラスト（ワイヤーフレーム／DS）、あるいは目標を実現する価値があるか（PRD）は、このゲートの対象外です。
• 曖昧な判定。 「ほぼ承認ですが……」や判定行が二つある状態。判定は必ず一つだけにしてください。

出力

1 つのユーザーフロードキュメントに対する、単一のレビュー結果：

• 判定行を 1 行 — VERDICT: approve または VERDICT: revise を、独立した行にそのまま記載します。
• 指摘事項 — revise の場合、阻害要因となる欠落ごとに、対応可能な指摘を 1 件記載します（不合格となった条件 + 該当箇所 + 具体的な修正方法）。approve の場合、阻害要因とならない注記は任意です。

この抽象的なコンシューマーは、作成→レビューのループを統括するものです。approve は次のフェーズ（ワイヤーフレーム作成）に向けてユーザーフロードキュメントを承認し、revise は指摘事項を作成者に返して、範囲を限定した修正を依頼します。

関連項目

• authoring-user-flows — 作成を担う側です。このスキルが評価するのと同じ基準でフローを作成します。両者を組み合わせることで基準を一本化し、作成とレビューの間でずれないようにします。
• wireframes-review スキル — 次のドキュメント（画面ごとのレイアウトと画面ごとのピクセル単位のアクセシビリティ）を対象とする、対応するゲートです。別のゲートであり、基準も異なります。このスキルは、画面一覧を作成するためのナビゲーショングラフと経路の完了可能性を評価します。
• PRD-review スキル — 上流のドキュメント（目標／ペルソナ／指標）を対象とするゲートです。このスキルは目標に対する網羅性を確認しますが、目標そのものを再評価することはありません。
• ユーザーフローテンプレート／content-template ツール — セクションの構成を担います。このスキルが評価するのは、構造への準拠ではなく、基準に照らした品質です。

段階的な開示

• references/completeness-walkability-bar.md — 13 の条件について、条件ごとの合格／不足の判断基準、比例性に応じた適用除外、調査結果の具体例を詳しく説明しています。境界的な条件について、より明確に合格／不足を判断する必要がある場合に読み込んでください。
• references/sources.md — レビューメソッド、フローとジャーニーの境界、レジリエンス／アクセシビリティ／品質の条件、差分レビューの調査根拠です。

本文の上限

• description は 1,024 文字以下（agentskills.io の上限）です。Claude は一覧表示で description と when_to_use の合計が 1,536 文字を超えると切り詰めます。
• 本文は約 500 行／5,000 トークン（目安。品質を優先し、継続的に 700 行／7,000 トークンを超える場合は指摘してください）です。各ターンでコンテキストに保持されます。
• 参照ファイルごとに、10k トークンを超えた場合は警告し、25k を超えた場合はエラーとします。参照ファイル全体では、25k トークンを超えた場合は警告し、50k を超えた場合はエラーとします。