ux-foundation

ux-foundation — WHY レイヤー

super-ux の一部です — パイプライン全体（foundation → flows → screens → scenarios → audits → plans）と4つの同期ルールについては、system-map.md を参照してください。変更後はリンターを実行してください （python3 docs/ux/lint.py）。

WHO が使い、WHY 使うのかを知らずに構築されたインターフェースは失敗します。このスキルでは docs/ux/foundation.md を管理します：ペルソナ → Jobs to Be Done → カスタマージャーニー → ユーザーストーリー。 シナリオ（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のステートメントでは、状況、動機、成果を明確にします。機能を述べるものではありません（「新しい顧客を獲得したときに、すっきりしたワークスペースを作りたい。そうすれば、請求を別にできるから」。「プロジェクトのドロップダウンがほしい」ではありません）。4つの力、つまりプッシュ、プル、不安、習慣を記録します。
• ジャーニーでは、プロダクトを利用する前、利用中、利用後を含む一連の体験を、ステージごとに1行で記録します。項目は、行動、タッチポイント、感情（1～5）、ペイン、機会です。フォーマットの規定に従って、マップのオーナー（または unknown）を記録します。マップを書いた人がそのオーナーになるわけではありません。機会は「頻度 × 深刻度 × 解決可能性」で評価します。各要素には SOURCE と SCALE を付記するか、値を unknown とします。誰も測定していない要素に、セルを埋めるためだけに数値を作ってはいけません。また、感情（1～5）にも、誰が報告したのか（オーナーの見解か、観察したセッションか）を記録します。評価らしく見せた推測ではいけません。機会を記入する際は、ステージタグを使ってbest-practices.mdを参照し、実証済みの仕組みを確認してください。
• どのモデルを適用しているか、またその限界はどこか。 product-frameworks.md （PF-01..PF-12）には、このレイヤーが参照するモデルが名前付きで記載されており、それぞれに知っておく価値を生む失敗モードが示されています。人々が乗り換えない理由を説明する力、それを明らかにするインタビュー、2つのソリューションを比較可能にするツリー、そしてすべてのオンボーディング設計が依拠するアクティベーションの定義です。2つは入力ではなく、順序に関する制約です。オンボーディングに取り組む前に PF-07 を、PF-01 の前に PF-02 を適用します。
• **有料獲得型のプロダクトでは、ペルソナを書く前に市場を読み解きます。**購入者は誰かの広告を通じて訪れ、カテゴリはすでに、誰がそれに反応するかを知るための学習コストを支払っているからです。 funnel-research.mdにはその手法が記載されています。FR-01 で実際のファネルを収集し、FR-02 で収益が見えない場合にも残る4つのシグナルを読み取り、FR-05 でどの隣接カテゴリから学びを転用できるかを特定します。FR-07 は各調査結果を独立した文書ではなく、ここに反映します。市場調査はペルソナに情報を与えますが、ペルソナを決定するものではありません。コーパスだけをもとに作られた基盤は、競合のオーディエンスに向けられてしまいます。
• **すべての調査結果には、その出所を添えます。**調査を統合したり、基盤文書に数値を記載したりする際は、research-evidence.mdを参照してください。観察、引用、推論、仮説はそれぞれ別の分類です。矛盾する参加者の意見も関連付けたままにします。数値には単位、対象、母集団、日付を付けます。データがないものは仮説のままにします。必要なエビデンス数のノルマはありません。合成ペルソナやLLMによる「デジタルツイン」はエビデンスではありません。その出力は、実際のユーザーまたは実データによって確認されるまでは仮説です。
• 台帳はローカルにあり、新たなルートではありません。基盤が参照する docs/ux/research-ledger.md に、基盤と並べて保存します。調査の統合は基盤の作業に含まれるステップであり、独立したパイプラインではありません。ディスク上にあるトランスクリプトは、それだけで完全な入力です。ローカルの資料を台帳の行に変換するために、Notion、Dovetail、ブラウザー、API キーは必要ありません。必要のないツールを待って統合が滞るなら、それは依存関係を作り出したということです。
• エビデンス ID と不明点は、シナリオにも引き継ぎます。ペルソナの特性やジャーニーのステージには、それを裏付ける RE- ID を引用し、その上に構築するシナリオにもそれらの ID を引き継ぎます。トレースの連鎖が運ぶのは構造だけでなく、出所情報です。シナリオの作成に影響した仮説は、そのシナリオ内に明示的な不明点として残します。途中でそれを落とすと、推測が事実のような顔をしてインターフェースに現れます。
• ストーリーは INVEST を満たし、受け入れ条件は Given/When/Then 形式で観察可能なものにします。検証できないストーリーは、まだ書き終えていません。
• 意見よりエビデンスを重視します。複数のユーザーに繰り返し見られるペイン、観察可能な回避策、測定可能なコストがエビデンスです。ステークホルダー1人のアイデアは事実ではなく仮説です。仮説には（望ましさ／事業性／実現可能性／ユーザビリティ）のラベルを付け、リスクが高く未検証のものにはフラグを立てます。
• **レビューとサポートチケットは、すでに手元にあるエビデンスです。**時間のない人たちへのインタビューを予定する前に、アプリストアのレビューとサポートキューを読み、称賛、機能リクエスト、バグ、操作上の不満に分類します。操作上の不満は、ユーザー自身の言葉で記されたジャーニー上のペインです。他のエビデンスと同じように、ジャーニーの行に出典と日付を引用します。これは WHY レイヤーが得られる最も安価な入力であり、調査らしく感じられないという理由で最も見過ごされがちなものです。

ワークフローの選択

状況	ワークフロー
foundation.md がない、新規プロダクト	Init（インタビュー）
foundation.md がない、既存のプロダクト／シナリオがある	Init（逆解析）
ユーザーに関する理解が変わった	Update
一貫性に疑問がある、または上に構築する前	Validate

docs/ux/ がない場合は作成し、このスキル独自の templates/foundation.md を基に foundation.md を用意してください。

Init（インタビュー）— ゼロからの立ち上げ

質問は一度に1つずつ行います。ユーザーの回答がデータになります。

1. 誰が使いますか？（→ ペルソナ。各ペルソナを具体的に認識できるまで掘り下げます）
2. ペルソナごとに、どのような状況がきっかけでこのプロダクトを使おうとしますか？本当に達成したいことは何ですか？どのような結果が得られれば成功だとわかりますか？ （→ JTBD ＋ 力学）
3. 利用前・利用中・利用後を通して、その人の道筋をたどります。どこから始め、何に触れ、現在どこに痛みを感じていますか？（→ ジャーニー、各段階の感情と課題）
4. ジャーニーの課題とジョブの成果からユーザーストーリーを導き出し、受け入れ基準を記述します。ジョブの成功指標に照らして、must／should／could の優先順位を付けます。
5. デザイン作業を始める段階で、デザインツールを記録します。Figmaを使うかどうかの選択（デフォルトはオン）、プロダクトのFigmaフォルダ、そしてプロダクトが持つ各サーフェス（App、Web、ASO）ごとに1ファイルずつ、そのファイルが管理する項目を記録します。すべてを1つのURLにまとめると、ストア用素材やサイトの保存場所が記録されないままになります。ビジュアルレイヤーに関するその他の情報（デザインシステム、スタイルパック、状態ごとのフレームリンク）は screens.md に記載します。figma-integration.md と visual-identity.md を参照してください。Figmaについての質問はプロジェクトごとに一度だけ行い、フローごとには行わないでください。
6. 次の3項目のうちいずれかに該当する場合は、プロダクトの仕組みを記録します（contract §7）。パーソナライズ、エンゲージメントの仕組み（連続記録／ポイント／リーダーボード）、プロダクトが採用するアクセシビリティの基準です。「なし」も有効な回答であり、記録する価値があります。プラクティスの選定ではこの3項目を参照し、ほかの情報から推測できないためです。
7. プロダクトが収益を得る場合は、収益化のセクションに記入します。データに基づいて選んだモデル（BP-067..070 — ハードペイウォール、フリーミアム、ハイブリッドのいずれか。トライアルの種類と期間）、価値指標、無料利用の境界、購入サーフェス（IAP、Webチェックアウト、またはweb2app — BP-030/BP-078/BP-127）、購入につながる場面、獲得施策との一貫性を記録します。購入につながる場面は後続工程で専用のフローになります。Webまたはweb2appの購入サーフェスがある場合、このプロダクトにはWebファネルと有料利用への引き継ぎフローも含まれます（BP-116..129）。
8. レイヤーごとに提示して承認を得ます。未検証の推測には、リスクに関する注記を添えて仮説として明示します。

Init（逆解析）— 既存プロダクト

1. 既存のものを棚卸しします。シナリオ、画面／ルート、オンボーディング、設定、利用可能な場合は分析／サポート関連の資料を確認します。
2. 逆解析します。現在のUIはどのようなジョブに暗黙的に対応していますか？どのようなペルソナを想定していますか？証拠に基づいてJTBD／ジャーニー／ストーリーの草案を作成し、確度（観察済みか推論か）を付記します。
3. ギャップを明確に示します。明確なジョブに対応していない機能（削除候補）、サポートされていないジョブ（機会）、課題があるのに対応がないジャーニーの段階を洗い出します。
4. 証拠を取り繕うのではなく、意思決定のために提示します。3つの軸はそれぞれ独立しています（references/scenario-format.md）。evidence_kind（brief／owner-belief／interview／telemetry／code-inference）、decision_status（proposed／accepted／rejected）、validation_status（unvalidated／observed／contradicted）です。オーナーが「確認しました」と言うことで、DECISIONはacceptedになりますが、evidence_kindは変わりません。唯一の証拠がowner-beliefである承認済みのペルソナは、依然として unvalidated であり、記録にもその旨を示します。実際のインタビューまたは観察があり、その日付入りの記録がある場合にのみ、validation_statusはobservedになります。創業者が承認しても、望ましいペルソナをobservedに変えることはできません。

更新

新しい知見（ユーザーからのフィードバック、分析結果、方向転換、新しいセグメント）が得られた場合：

1. ID で影響を受けるエントリーを特定し、ステートメント、ステージ、ストーリーを更新します。
2. 取りやめた方向性：ストーリーに dropped と記録し、エントリーは残します。削除しないでください。
3. 連鎖的な確認：変更した ID をたどれるシナリオはどれですか？一覧にして、同じセッション内でその一覧を ux-scenarios の（更新）に引き渡します。

テストパネル

プロジェクトが task-pipeline を通じてインターフェースを変更すると、design-tester は テストパネル（docs/ux/test-panel.md）を確認します。これは templates/test-panel.md にある 10 件の人物像です。まず基盤を作り、ペルソナごとに人物像を 1 件ずつ用意してから、アクティベーション段階（新規、アクティベーション中、アクティブ、離脱リスクあり、再訪）と、画面を変えるニーズ（小型スマートフォン、大きな文字、キーボードのみ、2 つ目のロケール、遅い接続）を網羅して、合計 10 件にします。少なくとも 2 件はローカル（エンゲージメントが高く、データがつながっており、友人経由で訪れたユーザー）で、少なくとも 2 件は観光客（エンゲージメントが低く、広告または割引経由で訪れたユーザー）とし、リテンションの線の開始位置に印を付けます。顧客生涯価値は前者に支えられ、解約の大半は後者から生じます（この内訳は references/funnel-research.md の Your own numbers を参照してください）。各人物像には、その特徴、SCR- ID による 2～4 件の複合シナリオ、アクティベーションファネルとリテンションループ、および根拠の行（evidence RE-NN または hypothesis）を記載します。パネルはテスト用の仕組みです。前述の品質基準は引き続き適用されるため、仮説に基づく人物像は何をテストするかを決めるものであり、何を構築するかを決めるものではありません。担当者がパネルを一度承認し、プロダクトに変更があれば改訂します。ゲートは task-pipeline の design_gate.py panel docs/ux/test-panel.md です。

検証

1. 整合性： ID が連番かつ一意であること、すべてのストーリーがジョブにたどり着けること、すべてのジャーニーがペルソナ × ジョブに属していること、ステータスが有効であること。
2. 品質： JTBD ステートメントが状況／動機／成果で構成されていること（機能を含まないこと）、ストーリーが INVEST を満たしていること、受け入れ基準が観察可能であること、ジャーニーの全レイヤーが記入されていること。
3. 網羅性： すべてのペルソナに 1 件以上のジョブがあること、すべてのジョブに 1 件以上のジャーニーと 1 件以上のストーリーがあること、scenarios.md にすべての must／should ストーリーに対応するシナリオが 1 件以上あること（または、明示的に未対応であること）。
4. 項目ごとの修正内容を添えたチェックリストとして報告し、承認された修正を適用します。

完了の定義

• レイヤー間に一貫性があり、ID が安定しており、仮定にはその旨が明記されていること。
• 新規または変更されたエントリーについて、ユーザーの承認を得ていること。
• 連鎖する更新を特定し、後続の担当に引き渡していること（影響を受けるフローは ux-flows、影響を受けるシナリオは ux-scenarios に引き渡します）。連鎖が気付かれないまま変化することはありません。
• 次のレイヤーを提示すること：ストーリーの準備ができたら、UI 作業の前に ux-flows がそれをユーザーフローに変換します。

references/ にあるその他の内容。 このスキルは契約を 8 件直接指定していますが、references/ には 14 件あります。これは、このスキルが指定する契約からほかの契約へリンクしており、依存関係全体をスキル内に含めて配布するためです。skills CLI は 1 つのディレクトリをインストールするので、兄弟ディレクトリにあるファイルは参照先がない状態で届いてしまいます。ここで指定されているものを開いてください。残りは、契約から名前を指定されたときに、そこからたどってください。