┌─────────────────────────────────────────────────────────────┐
│  SSOT 構造 (v2.0 - Frontmatter ベース)                      │
├─────────────────────────────────────────────────────────────┤
│  docs/research/*.md Frontmatter   → リサーチメタデータ (SSOT) │
│                                      スキーマ: docs/_schemas/ │
│                                      research-frontmatter.  │
│                                      schema.json            │
│  docs/_manifests/research-manifest.json                     │
│                                   → Frontmatter から自動    │
│                                      生成されたキャッシュ (読取専用)│
│  assets/research-status.json      → リサーチ作業状態 (SSOT)  │
│  references/kpi-targets.md        → KPI 定義 + Feature マッピング │
│  references/critical-gaps.md      → クリティカルギャップリスト        │
│  docs/features/                   → 動的スキャン (SPEC 読込)    │
│  docs/research/README.md          → 文書リスト (参照用)       │
└─────────────────────────────────────────────────────────────┘

⚠️ 禁止: 同じデータを複数ファイルにハードコーディングしない。
   - Feature Tier は kpi-targets.md でのみ定義
   - リサーチ状態は assets/research-status.json でのみ管理
   - リサーチメタデータは各文書の Frontmatter でのみ定義
   - Manifest は直接修正しない (スクリプトで自動生成)
   - README.md は文書リストのみ、状態管理 X

# スキャン対象
features = scan("docs/features/*/PRD-*.md")  # 28個 Feature
research = scan("docs/research/*.md")         # 99個 リサーチ

# 例示: D7 リテンション KPI
d7_retention:
  target: 25%+
  primary_features: [004, 005, 006, 023]
  required_research:
    - FTUE 最適化 (ftue, onboarding, first-time)
    - 習慣形成 (habit, streak, routine)
    - プッシュ通知 (notification, push, reminder)

優先順位スコア = (KPI 影響度 × 3) + (実装容易性 × 2) + (Japan-First 適合性 × 1)

{
  "job_id": "{topic}-{year}",
  "topic": "{リサーチ主題}",
  "phase": "processing",
  "provider": "openai|google",
  "created_at": "{現在時間}",
  "started_at": "{現在時間}",
  "ttl_expires_at": "{現在時間 + 24h}",
  "kpi_target": "{関連 KPI}",
  "priority": "P0|P1|P2"
}

## リサーチ要求: {gap_topic}

### 目標

プロジェクト アプリの {kpi_target} 達成

### コンテキスト

- Japan-First 戦略 (日本市場優先)
- 効率性重視 (自動化/低コスト必須)
- AI コンテンツ 100% (著作権 Free)

### 必須含む内容

1. 定量的データ (% 数値、ベンチマーク)
2. 競合社比較 (Duolingo, Speak, ELSA)
3. 実行可能な Action Items
4. 日本市場特殊性反映

### 出力形式

- 言語: 韓国語
- 形式: マークダウン
- 長さ: 1500-3000 単語

{topic}-{subtopic}-{year}.md
例: churn-prevention-program-design-2026.md

# AI メタデータ抽出ロジック (概念的)
def extract_metadata(document_content, topic, kpi_target):
    # 1. research_id 生成: R-{YYYYMMDD}-{順番}
    research_id = generate_research_id()

    # 2. category 自動決定
    category = classify_category(document_content)
    # 規則: 競合社言及多 → competitor
    #       価格/収益主題 → monetization
    #       技術詳細 → technical
    #       既定値 → strategy

    # 3. kpi_relevance: kpi_target + 本文キーワード分析
    kpi_relevance = detect_kpi_keywords(document_content, kpi_target)

    # 4. feature_domains: 本文から機能キーワード抽出
    feature_domains = extract_feature_keywords(document_content)

    # 5. competitors: 本文から競合社名抽出
    competitors = extract_competitor_names(document_content)

    # 6. scanner.keywords: 核心キーワード抽出 (上位 5-10個)
    keywords = extract_top_keywords(document_content)

    # 7. scanner.priority: kpi_relevance + category で決定
    priority = calculate_priority(kpi_relevance, category)

    # 8. quality 評価
    quality = assess_document_quality(document_content)

    # 9. 検索メタデータ抽出 (全てのリサーチ文書に適用)
    # 9.1 target_apps: 本文からアプリ名抽出
    target_apps = extract_app_names(document_content)

    # 9.2 target_user_levels: レベルキーワード抽出
    target_user_levels = extract_user_levels(document_content)

    # 9.3 pain_points: ペインポイントカテゴリキーワードマッチング
    pain_points = extract_pain_point_categories(document_content)

    # 9.4 learning_topics: 韓国語学習主題抽出
    learning_topics = extract_learning_topics(document_content)

    # 9.5 actionability: 実行可能性自動判断
    actionability = determine_actionability(document_content)

    return frontmatter_dict

def extract_app_names(content):
    """本文からアプリ名抽出"""
    app_keywords = {
        "duolingo": ["デュオリンゴ", "duolingo", "デュオリンゴ"],
        "ttmik": ["TTMIK", "Talk To Me In Korean", "トークトゥミーインコリアン"],
        "sejong": ["世宗学堂", "sejong", "世宗韓国語"],
        "speak": ["Speak", "スピーク"],
        "elsa": ["ELSA", "エルサ"],
        # ... 其他アプリ
    }
    found = []
    for app, keywords in app_keywords.items():
        if any(kw.lower() in content.lower() for kw in keywords):
            found.append(app)
    return found

def extract_user_levels(content):
    """本文からユーザーレベル推定"""
    level_keywords = {
        "beginner": ["初級", "入門", "beginner", "初心者", "A1", "A2"],
        "elementary": ["初中級", "elementary", "B1"],
        "intermediate": ["中級", "intermediate", "B2"],
        "advanced": ["高級", "advanced", "C1", "C2", "ネイティブ級"]
    }
    found = []
    for level, keywords in level_keywords.items():
        if any(kw in content for kw in keywords):
            found.append(level)
    return found

def extract_pain_point_categories(content):
    """ペインポイントカテゴリ自動分類"""
    category_keywords = {
        "content": ["コンテンツ", "内容", "資料", "教材", "品質"],
        "learning_design": ["学習設計", "カリキュラム", "進度", "難易度"],
        "ux_ui": ["UX", "UI", "インターフェース", "デザイン", "画面", "操作"],
        "motivation": ["動機付け", "面白さ", "退屈", "興味", "習慣"],
        "technical": ["バグ", "エラー", "遅い", "クラッシュ", "エラー"],
        "pricing": ["価格", "高い", "サブスク", "無料", "有料"],
        "social": ["ソーシャル", "友達", "コミュニティ", "リーダーボード", "競争"]
    }
    found = []
    for category, keywords in category_keywords.items():
        if any(kw in content for kw in keywords):
            found.append(category)
    return found

def extract_learning_topics(content):
    """韓国語学習主題抽出"""
    topics = ["発音", "文法", "語彙", "会話", "読み", "書き込み", "聞き取り",
              "敬語", "タメ口", "方言", "スラング", "文化文脈",
              "ハングル字母", "パッチム", "発音変化"]
    return [topic for topic in topics if topic in content]

def determine_actionability(content):
    """実行可能性自動判断"""
    has_actions = "## Action Items" in content or "- [ ]" in content

    # 緊急性キーワードチェック
    immediate_keywords = ["即座", "緊急", "速く", "critical", "P0"]
    review_keywords = ["検討必要", "考慮", "分析必要", "P1"]
    long_term_keywords = ["長期", "ロードマップ", "未来", "P2"]

    if any(kw in content for kw in immediate_keywords) and has_actions:
        return ["immediate"]
    elif any(kw in content for kw in review_keywords):
        return ["review_needed"]
    elif any(kw in content for kw in long_term_keywords):
        return ["long_term"]
    else:
        return ["reference_only"]

---
research_id: R-20260206-001
title: 'Duolingo アプリストアレビューペインポイント分析 2026'
category: user
kpi_relevance:
  - monthly_churn
  - d7_retention
feature_domains:
  - content
  - retention
competitors:
  - duolingo
target_apps:
  - duolingo
target_user_levels:
  - intermediate
  - advanced
pain_points:
  - content
  - learning_design
  - motivation
learning_topics:
  - 発音
  - 文法
  - 会話
actionability:
  - immediate
  - review_needed
scanner:
  scannable: true
  priority: P0
  expected_insights:
    - feature_gap
    - user_behavior
  keywords:
    - duolingo
    - intermediate
    - 発音
    - コンテンツ
    - ペインポイント
quality:
  actionable: high
  source_reliability: A
  has_data: true
  has_actions: true
created_at: 2026-02-06
created_by: research-gap-analyzer
ai_confidence: 0.85
schema_version: 3
---

{
  "phase": "completed",
  "doc_path": "docs/research/{ファイル名}.md",
  "completed_at": "{完了時間}"
}

{
  "phase": "failed",
  "last_error": "{エラーメッセージ}",
  "attempt": 2
}

# AI が自動的に実行 (人間介入不要)
Bash: python scripts/generate_research_manifest.py

# Frontmatter スキーマ検証 (問題発生時のみ)
Bash: python scripts/validate_research_frontmatter.py

---
research_id: R-{YYYYMMDD}-{NNN} # 必須、固有 ID (例: R-20260126-001)
title: '{文書タイトル}' # 必須 - 最初の # ヘッダーから抽出
category: strategy # 必須 - 9個 enum (自動分類)
kpi_relevance: # 関連 KPI (kpi_target + 本文分析)
  - ltv
  - monthly_churn
feature_domains: # 関連機能ドメイン (本文キーワード)
  - retention
  - monetization
competitors: # 言及された競合社 (本文から抽出)
  - duolingo
  - speak
scanner: # market-intelligence-scanner用
  scannable: true
  priority: P1 # P0|P1|P2|P3 (自動計算)
  expected_insights:
    - feature_gap
    - pricing
  keywords: # 本文核心キーワード 5-10個
    - churn
    - retention
quality: # 文書品質 (自動評価)
  actionable: high # high|medium|low
  source_reliability: B # A|B|C (ディープリサーチソース基準)
  has_data: true # 数字/% 含有有無
  has_actions: true # Action Items 存在有無
created_at: 2026-01-26 # YYYY-MM-DD (今日日付)
created_by: research-gap-analyzer
ai_confidence: 0.85 # 0.6~0.9 (ソース品質基準)
schema_version: 1
---

# AI 自動実行ロジック
1. Read("docs/research/README.md")  # 現在リスト読取
2. アルファベット順挿入位置計算
3. Edit()で新項目挿入

- [x] [{Frontmatterの title}](./{ファイル名}.md)

# 1. Read で現在状態確認

- [x] [Churn Prevention Strategy 2025](./churn-prevention-strategy-2025.md)
- [x] [Competitor Analysis 2026](./competitor-analysis-2026.md)

# 2. 挿入位置計算: "churn-r..." → "churn-p..." 次

# 3. Edit で挿入

- [x] [Churn Prevention Strategy 2025](./churn-prevention-strategy-2025.md)
- [x] [Churn Reactivation Campaign 2026](./churn-reactivation-campaign-2026.md) ← 自動挿入
- [x] [Competitor Analysis 2026](./competitor-analysis-2026.md)

.claude/skills/research-gap-analyzer/
├── SKILL.md                           # このファイル (ワークフロー定義)
├── assets/
│   └── research-status.json           # リサーチ作業状態 (SSOT)
├── references/
│   ├── kpi-targets.md                 # KPI 定義 + Feature マッピング
│   ├── critical-gaps.md               # クリティカルギャップリスト
│   └── research-status-schema.json    # 状態ファイル JSON スキーマ
└── scripts/
    └── analyze_gaps.py                # 自動化スクリプト (選択的)