app-store-review-arbitrage

app-store-review-arbitrage

競合アプリの App Store または Google Play の URL を、1 回のセッションで作成できる GTM ブリーフに変換します。レビューの原文を情報源として、苦情クラスターのランキング、破られた約束のマップ、ランディングページの見出し、広告コピーの方向性をまとめます。

---

重要なルール（ステップ 1 の前にお読みください）

以下のルールはすべてのステップに適用されます。違反すると、セルフ QA（ステップ 6）に失敗します。

1. 引用はすべて原文どおりにしてください。 言い換え、文法の修正、文面の整理はしないでください。レビュアーが書いた言葉をそのまま使用してください。
2. 統計を捏造しないでください。 レビュアーが同様の表現を明示的に使っていない限り、「40% 高速」や「信頼性が 2 倍」などと書いてはいけません。セルフ QA ステップでは、出典のないパーセンテージをチェックします。
3. クラスター名にはレビュアーの言葉を使用してください。 ステップ 3 のアンチパターン表を確認してください。
4. 見出しと広告コピーの方向性には、必ず出典となるクラスターを記載してください。 形式：[cluster: "cluster-name"]
5. 出力には必ずセクション 2 を含めてください。 劣化した状態でも省略してはいけません。
6. 生成するコピーに、禁止語を使用しないでください。 powerful、robust、seamless、innovative、game-changing、streamline、leverage、revolutionize、transform

---

ステップ 1 — 入力を解析してプラットフォームを検出する

アプリの URL を 1 つ含む自然言語のプロンプトを受け取ります。URL を抽出してください。

プラットフォームの検出：

• apps.apple.com → App Store
• play.google.com/store/apps/details?id= → Google Play
• 上記以外の URL → 停止して、次のように応答してください：「App Store または Google Play の直接 URL を指定してください。他のソースからレビュー データを分析することはできません。」

ID の抽出（スクリプトを呼び出す前に実行してください）：

プラットフォーム	抽出するもの	方法
App Store	数値の app_id	URL 内の /id の後にある数字
App Store	country	apps.apple.com/ の後にある 2 文字のコード（例：us、gb）
Google Play	package_name	id= クエリパラメーターの値

抽出した値を保持してください。ステップ 7 で出力ファイル名を作成する際に必要になります。

ユーザーのプロンプトに product_context（ユーザー自身の製品の機能）が含まれている場合は、保存してください。ステップ 5 でコピーをパーソナライズするために使用します。

---

ステップ 2 — レビューとメタデータを収集する

取得スクリプト全体を実行してください。

python3 scripts/fetch_reviews.py "{app_url}" --output {tmpdir}/asr-raw.json

(注：{tmpdir} は、お使いのオペレーティングシステムの一時ディレクトリに置き換えてください。例：macOS/Linux では /tmp、Windows では C:\Temp。)

このスクリプトは、ストアの説明メタデータとレビューの両方を取得します。

• App Store： iTunes API — 無料、認証不要。App Store のレビューは Apple の公開 iTunes RSS フィードから取得します。Apple API の制限により、レビューが 0 件になるアプリもあります。その場合、このスキルは利用可能なデータを使って続行し、警告を記録します。主にサポートされているのは Google Play です。
• Google Play： google-play-scraper パッケージ — 無料、認証不要

スクリプトが失敗した場合は、stderr からエラーを確認してください。よくある原因：

• パッケージがインストールされていない：pip install google-play-scraper を実行してください
• アプリが見つからない：URL が現在有効な掲載ページを指しているか確認してください
• Google Play API エラー：pip install --upgrade google-play-scraper を実行してから再試行してください

スクリプトは収集の進行状況を stderr に出力します。完了するまで待ってください。完了したら、{tmpdir}/asr-raw.json を読み込み、収集の概要をユーザーに表示してください：

✓ Collected [N] reviews ([N] low-star 1–3★) from [platform]
  Date range: [oldest] to [newest]
  Package: [iTunes API | google-play-scraper]

終了コードを確認してください：

• 終了コード 0 → 収集に成功しました。metadata.store_description を確認してください。null の場合は、その旨を記録してください。セクション 2 では劣化した状態を使用します。ステップ 3 に進んでください。
• 終了コード 1 → エラーです（stderr のメッセージを読み取り、ユーザーに伝えて停止してください）
• 終了コード 2 → ゲート 1 が作動しました（低評価レビューが 10 件未満）

ゲート 1 — シグナル不足による停止： スクリプトが終了コード 2 を返した場合は、{tmpdir}/asr-raw.json から gate_message を読み取り、そのままユーザーに伝えてください。ステップ 3 に進んではいけません。部分的なブリーフも作成しないでください。

---

ステップ 3 — 苦情のクラスタリング

{tmpdir}/asr-raw.json から low_star_reviews を読み込みます。

評価の低いレビューをすべて、名前付きの苦情テーマ 4～6 個にクラスタリングします。各レビューのスコアには、次の計算式を適用します。

complaint_weight = (4 - rating) × recency_factor

recency_factor:
  review age ≤ 90 days  → 1.0
  review age 91–365 days → 0.7
  review age > 365 days  → 0.4

review age ＝（今日の日付）−（レビューの date フィールド）の日数。

cluster_score ＝ クラスター内のすべてのレビューの complaint_weight の合計。

クラスターの命名 — 重要なルール：

抽象的な名前を付けたくなるかもしれません。そうしないでください。レビューにある動詞と名詞をそのまま使います。

❌ 抽象化（誤り）	✅ レビュアーの表現（正しい）
「安定性の問題」	「PDF にエクスポートするとクラッシュする」
「同期の問題」	「スマートフォンとデスクトップ間の同期後にデータが消えた」
「収益化の摩擦」	「14 日間と約束されていたのに、3 日後にペイウォールが表示される」
「パフォーマンスの低下」	「検索するたびにアプリがフリーズする」
「オンボーディングの問題」	「チームメイトの招待方法がわからない」

ルール：

• 各レビューは、必ず 1 つのクラスターにのみ所属します（主なテーマに割り当てます）
• レビューが 3 件未満のクラスターは破棄し、ノイズとして記録します
• 各クラスターにつき、逐語引用を 3～4 件選びます。星評価が低いものを優先し、次に新しいものを選びます

ゲート 2 — クラスターの最小サイズ： 3 件未満のクラスターを破棄した後、残ったクラスター数を確認します。

ゲート 3 — 低信頼度フラグ： 残ったクラスターが 3 個未満の場合：

• 処理を中断しないでください。出力を続けます。
• アプリのメタデータの直後、概要ヘッダーの先頭に次の文を追加します。

  ⚠ 信頼度が低い： 最低限の証拠基準（裏付けとなるレビューが 3 件以上）を満たした苦情クラスターは [N] 個のみでした。出力は限られたデータを反映しています。レビュー数の多い競合他社を検討するか、評価のフィルター範囲を広げてください。

• Medium ティアのクラスターを出力に含めます（スコア ≥ 5）

ティア分類（セクション 1 のリーダーボード表用）：

• Critical：スコア ≥ 60
• High：スコア 15～59
• Medium：スコア 5～14（ゲート 3 が適用される場合のみ含めます）
• Noise：スコア < 5（破棄し、含めません）

クラスターを {tmpdir}/asr-clusters.json に書き込みます。

{
  "clusters": [
    {
      "name": "cluster name in reviewer language",
      "score": 34.5,
      "tier": "High",
      "review_count": 14,
      "verbatim_quotes": [
        {"rating": 1, "text": "exact reviewer words", "date": "YYYY-MM-DD"},
        ...
      ]
    }
  ],
  "discarded_noise": 2,
  "gate_3_triggered": false
}

---

ステップ 4 — 破られた約束の検出

このステップこそが、このスキルを既存のあらゆるツールと差別化するものです。独立した名前付きステップとして必ず実行してください。

次を読み込みます。

• {tmpdir}/asr-raw.json の metadata.store_description
• {tmpdir}/asr-clusters.json のすべてのクラスター

store_description が null の場合： store_description_available: false に設定します。broken_promises 配列を空にし、下記の指定に従った detection_note を設定して、{tmpdir}/asr-promises.json に書き込みます。ステップ 5 に進みます。

ストアの説明が利用可能な場合：

1. 主張を抽出します。 主張とは、アプリの動作について具体的かつ検証可能な記述です。定義と例の詳細については、references/broken-promise.md を参照してください。曖昧な最上級表現、チームの説明、報道機関の引用は除外します。

2. 相互照合します。 主張ごとに、すべてのクラスター名と逐語引用を確認します。クラスターが約束された動作の不履行を直接記録している場合（最低 3 件のレビュー）、矛盾があると判断します。

3. 破られた約束の記録を作成します — 確認された矛盾ごとに 1 件作成します。

   {
     "claim_text": "verbatim excerpt from store description",
     "complaint_cluster": "exact cluster name",
     "gap_label": "Claims X; users report Y",
     "evidence_count": 18
   }
   

{tmpdir}/asr-promises.json に書き込みます。

{
  "store_description_available": true,
  "broken_promises": [...],
  "no_contradictions_found": false,
  "detection_note": null
}

縮退状態：

• 説明がない場合：store_description_available: false、detection_note: "Store description unavailable (fetched YYYY-MM-DD, returned empty). Broken promise comparison cannot be performed."
• 矛盾がない場合：no_contradictions_found: true、detection_note: "No broken promises detected. Store description does not appear to overclaim relative to complaint clusters."

フラグ付けしてはいけないパターンについては、references/broken-promise.md を参照してください。

---

ステップ 5 — コピーを作成する

ステップ 3 のクラスターとステップ 4 の破られた約束を使って、ブリーフのセクション 3〜5 を作成します。

コピーのルール（3 つのセクションすべてに適用）：

• すべての見出しと方針に、出典クラスターを記載します：[cluster: "cluster-name"]
• 禁止語は使用しないでください：powerful, robust, seamless, innovative, game-changing, streamline, leverage, revolutionize, transform
• 統計を捏造しないでください — レビュアーが使用した場合を除き、パーセンテージや数値は使わないでください
• product_context が指定されている場合：「こう伝える」の方針は、その製品の機能に即した内容にします。指定されていない場合は、ユーザーが内容を記入するポジショニング用テンプレートを作成します。
• 見出しにはレビュアーの言葉を使います — 実際のレビュー文をもとにするか、引用します

セクション 3 — ランディングページの H1 候補（3〜5 件）：

• 各項目："[headline text]" [cluster: "cluster-name"]
• 可能な限り 8 語以内にします
• 不満を抱えているユーザーに直接呼びかけます

セクション 4 — 広告コピーの方針（ペアをちょうど 3 組）：

Cluster: [cluster name]
Not that: "[what the competitor claims or a generic weak alternative]"
Say this: "[counter-claim grounded in complaint evidence]"
Evidence: [N] reviewers reported [verbatim complaint summary]

セクション 5 — 避けるべき主張：

• ステップ 4 の破られた約束ごとに警告を 1 件作成します
• セクション 2 が劣化状態の場合：単一の注記を記載します（正確な文言は references/brief-format.md を参照）

---

ステップ 6 — セルフ QA

保存する前に、作成したブリーフが以下のチェック項目を満たしていることを確認します。チェックに失敗した場合は、該当箇所を修正して再確認してください — 不合格のブリーフは保存しないでください。

チェック	ルール
引用文をそのまま掲載	すべてのクラスターに、引用文が 2 件以上ある
禁止語なし	セクション 3〜5 に、禁止語 9 語が一切含まれていない
出典のないパーセンテージなし	出力内の % はすべて、レビュアーが実際に記した言葉にたどれる
コピーにすべて出典を記載	すべての見出しと「こう伝える」に、[cluster: "name"] の出典が記載されている
クラスター数 ≥ 1	ゲート 2／3 を通過したクラスターが少なくとも 1 つある
セクション 2 がある	セクション 2 が出力内に含まれている（状態は問わない）
引用元レビューの評価 ≤ 3	引用文はすべて、評価が 1〜3★のレビューから取得されている

クラスター数に関する注記： 合格するブリーフに必要な最低クラスター数は 1 です（3 ではありません）。ゲート 3 の低信頼度フラグは、残ったクラスターが 3 未満の場合に適用されます。これは警告であり、不合格ではありません。クラスターが 0 件の場合に限り、セルフ QA は不合格となります。

---

ステップ 7 — 出力を保存する

references/brief-format.md の形式に従って、ブリーフ全体をまとめます。

保存先：

docs/review-briefs/[app-id]-[YYYY-MM-DD].md

docs/review-briefs/ ディレクトリが存在しない場合は作成します。

ブリーフ全体をユーザーに表示します。

一時ファイルをクリーンアップします：{tmpdir}/asr-raw.json、{tmpdir}/asr-clusters.json、{tmpdir}/asr-promises.json。