jmdevilleros/niche-map

ニッチマップ：概念空間のギャップ

このスキルは、あるドメインにおける根拠のあるギャップを見つけ出します。曖昧なランドスケープを、実在アイテム × 明示的な次元 のテーブルに変換し、誰も占有していない組み合わせやゾーンを探し、それらのギャップを具体的なアイデアに変換し、それらが幻影（ミラージュ）ではないことを確認します。

基本原則. 数値は判断を整理しますが、代替はしません。コードはアナリストの意思決定であるため、空間は市場と同じくらいルーブリックを反映します。だからこそ、提案されたすべてのギャップは、コードの信頼性チェック（ステップ2b）と外部検証（ステップ6）を生き残らなければなりません。

このリポジトリのツール

ファイル	役割
niche_core.py	ステップ3-4: エンコーディング、クラスター、PCA、UMAP、トリプルギャップ、密度ギャップ、候補近傍、供給対需要、図
recode_check.py	ステップ2b: ブラインド再コード化サンプルシートと次元ごとの一致度（Cohen's kappa）
md_to_pdf.py	ステップ7: MarkdownレポートをPDFに変換
templates/report_template.md	ステップ7: レポートの骨格
examples/	パイプライン全体をエンドツーエンドでテストするための合成・架空データセット

---

0. 入力とスコーピング質問

開始する前にこれらの回答を得てください。欠けているものがあれば、一度にまとめて質問してください。

入力	質問	なぜそれが重要なのか
トピックと境界	何がアイテムとしてカウントされますか？（例：「コアバリューがXであるツール」）	カテゴリの混在とギャップのアーティファクトを防ぎます。
N	アイテム数はいくつですか？（デフォルト80～100、実用的な最小値は約50）	Nが50未満の場合、三重カウントはノイズになります。
包含基準	最低限の認知度、入手可能性、プラットフォーム、言語、日付	ステップ1で適用され、文書化されます。
対象ユーザー	誰が成果物を構築または購入しますか？	適合スコアとtarget_filterの基礎となります。
制約	予算、時間、スキル、販売チャネル、除外トピック	target_filterと適合基準になります。
成果物	言語、通貨（および為替レートソース）、フォーマット	デフォルト: ランキング、ニッチカード、マップ、全コーパステーブル（リンク付き）を含むPDF。

1. コーパス：N個の実在、検証済みアイテム

1. 広範なシード. 多様なソース（ドメインストアやディレクトリ、「ベストオブ」リスト、「Xの代替」検索、最近のロングテールローンチ（ローンチサイト、ニッチディレクトリ、オープンソースレジストリ））から約1.3×Nの候補を収集します。有名な製品のみが含まれると、後で誤ったギャップが現れます。
2. アイテムごとの存在確認. 各アイテムには、解決可能なURL（ストアページ、価格ページ、またはリポジトリ）が必要です。HTTPステータス、最終URL、日付を記録します。サイトがボットをブロックする場合（403）、ドメインルートを確認するか、ブラウザを使用します。ブロックはアイテムが存在しないことを意味しません。
3. 認知度シグナル. 1つ以上の公開シグナル（ストアの評価とレビュー数、ローンチサイトの投票、リポジトリのスター、インストール数、受賞歴）を記録し、それぞれのソースとカバレッジを宣言します。シグナルがないという理由だけでアイテムを落とさないでください。認知度が包含基準である場合は、明示的なしきい値を適用します。
4. 重複排除. バリアント、リブランド、エディション、地域SKUを排除します。正規名とリンクを保持します。
5. 境界による除外. 包含基準を満たさないアイテムを除外し、理由とともにレポートにリストします。
6. コーパスバイアスチェック（回答をレポートに記述）：
   • ロングテール（例：過去24ヶ月以内にローンチされた、または認知度シグナルの中央値未満）からのアイテムの割合。約20％未満の場合は、さらにロングテールアイテムをサンプリングします。
   • ソース集中度：単一のソースがアイテムの約40％以上を占めてはなりません。
   • 指定された境界に対するプラットフォームまたは言語の偏り。
   • ソースごとのシグナルカバレッジ（一部のソースは特定のユーザータイプを過剰に代表します。例：コードホスティングサイトの開発者ツール）。

出力：items.csv、アイデンティティとリンク列を持つアイテムごとの1行、および検証の生JSON。

2. 次元、スケール、コーディングルーブリック

1. 8～15の次元を導出するには、約20のアイテムのサンプルを読みます。それらを2つのタイプに分割します：
   • 概念次元は、アイテムが何であるか を示します：動詞またはアクション、入力、出力、トリガー、ドメインまたはテーマ、ユーザー、美的感覚。ギャップはこれらを使用して検索されます（gap_dims）。
   • 属性次元は、それがどのように構築または販売されているか を示します：複雑さ、幅、セルフサービス、価格モデル、価格帯。これらはフィルタリングとスコアリングに使用されます。ギャップ検索で使用される場合、「メタ」ギャップ（例：「イベントトリガー + AIなし + 高複雑性」）を生成します。
2. スケール. 3～14の相互に排他的な値を持つ名義カテゴリ（それぞれに読みやすいラベル）、または記述されたアンカーを持つ短い順序尺度（0-1、0-2、1-3）。
3. 記述されたルーブリック: 値ごとに1行、定義と例アイテム、および以下の決定ルールを含みます。これはレポートの付録に含まれ、ステップ2bで2番目のコーダーが受け取る唯一の資料です。
   • 論理構造をコード化し、レンダリングをコード化しないでください。 空間的または構造的な次元については、ユーザーが実際にどのように相互作用するか、またはその物事について推論するかをコード化し、どのように見えるか（例：平面上で使用される3Dレンダリング製品は「3D」ではありません）をコード化しないでください。
   • 重複する値の優先順位。 名義スケールが知覚的またはスタイル的なもの（見た目、トーン、スタイル）を説明する場合、値は重複します。明示的な決定順序を与えてください（「Aが適用される場合はAをコード化、そうでなければB...」）、またはコーダーが区別できない値をマージします。
   • 順序尺度の測定可能なアンカー。 期間、サイズ、労力などのアンカーは、測定方法とそのソースを指定する必要があります（例：「ストアの説明に記載されている、またはデモビデオで観察された典型的なセッション。レベルベースのアイテムの場合は1レベル」）。観察できない場合は、最頻値をコード化し、フラグを立てます。
   • 主要モードをコード化。 アイテムがあいまいな場合は、その主要モードをコード化し、notes列に疑念を記録します。
4. 重み. デフォルト1.0。コア概念次元（例：動詞を1.2）を引き上げ、周辺的なもの（例：価格モデルを0.4）を下げます。各重みを正当化します。
5. 構造チェック：
   • 2アイテム未満のカテゴリがないこと。マージするか削除します（niche_core.pyが警告します）。
   • 冗長な次元を検出するためのクロス集計（相関 ≈ 1）：一方を削除またはマージします。
6. 限界を認める： コードは判断です。

出力：アイテム×次元のCSVと、スケール、重み、ルールを含むconfig.json。

2b. ブラインド再コード化チェック（必須）

目的：コードを決定するのはルーブリックであって、コーダーの記憶ではないことを測定します。信頼性の低い次元に基づくギャップは、ルーブリックのアーティファクトです。

1. サンプル. 固定シードを使用して、コーパスの10％（最低10アイテム）をランダムに抽出します： python recode_check.py sample --items items.csv --config config.json --out recode_sheet.csv --keep link シートには、アイテムIDとリンクのみが含まれ、次元列は空です。
2. 2番目のコーダー、ブラインド. 別の人物、または最初のコードを一度も見たことがない（items.csv、クラスター、レポートにアクセスできない）別のエージェントセッションが、記述されたルーブリックとアイテムの公開ページのみを使用してシートをコード化します。同じエージェントが行う必要がある場合は、新しいコンテキストを開始し、シートとルーブリックのみを提供します。比較する前に結果をロックします（例：チェックサムを保存）。
3. 次元ごとの一致度： python recode_check.py agree --items items.csv --config config.json --recode recode_sheet.csv --out agreement.csv
   • カテゴリカル次元：Cohen's kappa（κ）。
   • 順序次元：線形重み付きCohen's kappa（κw）。ニアミスに部分点を与えます。
   • 生のパーセント一致も併せて報告され、アイテムごとの不一致リストも報告されます。
4. しきい値. 次元は、κ（またはκw）≥ 0.60 かつ 生の一致度 ≥ 80％で合格します。n ≈ 10の場合、kappaはノイズが多いため、トリアージに使用し、すべての不一致を読んでください。
5. しきい値未満の場合、以下の順序で：
   1. 不一致を読み、分類します：ルーブリックのあいまいさ（重複する値、測定不可能なアンカー）、レンダリングと構造の混同、またはコーダーのエラー。
   2. ステップ2.3の決定ルールのいずれかを使用してルーブリックを修正します（優先順位、測定可能なアンカー、区別できない値のマージ）。
   3. 修正されたルーブリックでコーパス全体のその次元を再コード化し、その次元について新しい10％サンプル（新しいシード）でチェックを再実行します。
   4. それでも失敗する場合：その重みを下げ（≤ 0.6）、gap_dimsから削除するか、ドロップします。2回失敗した次元に依存する説明トリプルを持つギャップを報告しないでください。
6. 報告（次元、n、％一致、κ/κw、ステータス）、ルーブリックの変更、および2番目のコーダーのアイデンティティタイプ（人間、別のエージェント）を報告します。

典型的な結果：機能に関する次元（アクション、目標、入力/出力、トリガー）はよく一致します。知覚的または推定された次元（スタイル、空間構造、期間）が通常の失敗であり、それがステップ2.3の決定ルールが存在する理由です。

3. 空間：エンコーディング、クラスター、勾配、可視化

niche_core.pyによって実行されます。黄金律：クラスターとギャップは元のコード化空間で計算されます。UMAPは描画のみに使用されます。

• エンコーディング. カテゴリカル次元はOne-hot×重み/√2、順序次元は (x − min)/(max − min)。これにより、カテゴリを切り替えるコストは、順序尺度の端から端までの移動と同じになります。
• クラスター. 凝集型Ward。kは、k_range内のシルエットスコアによって選択されます。より大きなkは、シルエットが0.005以上改善する場合にのみ受け入れられます。
  • k範囲チェック： 選択されたkが範囲のいずれかの端にある場合、範囲を広げて再実行します。スクリプトが警告します。端に留まる場合は、解釈可能性に基づいてkを選択し、その旨を述べます。
  • カテゴリカルデータでは、シルエットスコア0.15～0.30が正常です。「明確なクラスター」として売り込まないでください。
  • 3アイテム未満のクラスターと同一ベクトルを持つアイテムはフラグが立てられます。後者は、ルーブリックがアイテムを区別するには粗すぎることを示唆します。
  • cluster_profiles.mdから手動で各クラスターに名前を付け、名前をcluster_namesに保存します。
• 勾配. PCAローディング（PC1-PC3、pca_loadings.csv）は、「AからBへ」の軸として読み取られます。
• 可視化. UMAP（n_neighbors 10-15、min_dist 0.25、固定シード）、KDE密度背景付き。制限：
  • グローバルな距離と島のサイズは無意味です。
  • transformは新しい点を最も近い島に引き寄せる傾向があるため、候補の新規性は元の空間のdist_minから読み取られ、プロットからは決して読み取られません。
• 次元間のペアワイズヒートマップは、空のセルを一目で示します。

4. ギャップ

4a. 組み合わせギャップ（トリプル）。 ギャップ（概念）次元の値のトリプルごとに、観測値と独立仮定下での期待値を比較します：e = N · p(a) · p(b) · p(c)、z = (e − o)/√e。トリプルは以下の場合に保持されます：

• o ≤ max_observed（デフォルト1）；
• e ≥ min_expected（デフォルト1.2）；
• トリプルのすべてのペアが少なくともmin_pair_supportアイテムに出現する（デフォルト2）：つまり、ピースは別々に存在する；
• 少なくとも1つのアンカー次元（anchor_dims、例：ドメインまたは動詞）に触れている。

メタギャップフィルター： 属性次元をgap_dimsから除外し、anchor_dimsを製品の内容を説明する次元に設定します。属性のみで構成されたトリプルはニッチではありません。

4b. 密度ギャップ。 50,000～400,000のランダムな合成ベクトルが生成され、以下の場合にのみ保持されます：

1. 値のすべてのペアが少なくとも1つの実在アイテムに存在する（既知のピースの再結合）；
2. 一貫性ルールがそれらを禁止していない（rules：ドメイン内で不合理な組み合わせ）；
3. それらが対象ユーザープロファイルに一致する（target_filter、例：複雑性 ≤ 1 かつ セルフサービス = 1）。これがユーザーフィットフィルターです：これがないと、密度ギャップはユーザーが構築または販売できない製品へと漂流します。

生存者は、最も近い実在アイテムまでの距離でランク付けされ、主要な概念次元（density_dedupe）で重複排除されます。異なる実在アイテム間の最近傍距離の中央値（median_nn_distance）と比較します。

4c. 供給対需要（オプション）。 クラスターごと：アイテム数（供給）対需要シグナル（レビュー、インストール数、検索ボリューム、スター）の中央値。常にそのカバレッジ（supply_demand_clusters.csv）とともに。需要が高い小さなクラスターはギャップのヒントです（推論）。

4d. 暫定スコア。 新規性（1～5、相対距離とギャップを説明するトリプルから）、実現可能性（1～5、ユーザーのリソースによるMVPの労力）、適合度（1～5、ステップ0からの好みと制約）。各候補について、candidatesに追加して最も近い3つの近傍をチェックし、再実行します。

5. 意味的変換：ベクトルからアイデアへ

最高z値のトリプルと最も遠い密度ギャップから8～12の候補を選択します。シグナルをマージし、重複を削除します。各候補は以下を取得します：

• 仮称と2～3文の具体的なピッチ：ユーザーが何をするか、製品が何を提供するか。
• すべての次元のベクトル。ルールを満たしている必要があります。
• 最も近いアイテム（距離×中央値）。
• なぜコーパスで空に見えるか： どのトリプルまたはゾーンがそれを説明するか、およびその次元のいずれかがステップ2bに失敗したかどうか。
• リスク： 技術的、市場的、適合性。

6. 外部検証とミラージュテスト

1. 候補ごとのターゲット検索、コーパス外：

   • 「[コンセプト] + アプリ/ツール + 価格」；
   • 「[コンセプト] 代替」；
   • 2～3の同義語でドメインストアを検索；
   • オープンソースリポジトリ。

   リンクと価格を含む3～5の競合を記録します。ほとんど常にいくつか現れると想定します： N ≈ 100のコーパスはロングテールをカバーしません。それに応じて新規性を調整します。

2. ミラージュテスト（ホワイトスペース分析 から適応、参考文献参照）。候補は4つの質問に直面します：

   • 規模： このジョブ・トゥ・ビー・ダンを持つ人は十分にいますか？
   • 支払いまたは切り替えの意欲： 最も強い証拠から最も弱い証拠まで、彼らはすでに部分的な解決策に支払っている、コストのかかる回避策を維持している、または自分で構築しようと試みた。
   • 既存企業の質問： なぜ誰もそれを埋めなかったのか？許容できる回答：ビジネスモデルまたはチャネルの競合、最近の外部変化、成長セグメント。憂慮すべき回答：「理由が見つからない」。
   • 勝ちやすさ： 対象ユーザーは、ギャップを空のままにしている障壁を克服できますか？

   評決：合格（係数1.0）、疑わしい（0.7）、または不合格（0.4）。

3. 最終スコア = 新規性 × 実現可能性 × 適合度 × ミラージュ係数（範囲 0.4～125）。

4. 検証で脱落した候補は「偽のギャップ」としてレポートに残ります。それらはコーパスのバイアスを露呈させます。

...