Analyse d'avis et arbitrage de positionnement

Arbitrage d'avis App Store / Google Play

Convertissez l'URL d'une application concurrente sur l'App Store ou Google Play en un brief GTM (Go-To-Market) complet en une session : clusters de réclamations classés, carte des promesses non tenues, titres de pages d'accueil et directions de copy publicitaire — le tout issu des avis textuels exacts.

---

Règles critiques (à lire avant l'Étape 1)

Ces règles s'appliquent à toutes les étapes. Toute violation entraîne l'échec de l'Auto-QA (Étape 6).

1. Chaque citation doit être textuelle. Pas de paraphrase, ni de correction grammaticale, ni de nettoyage. Uniquement les mots exacts des utilisateurs.
2. Aucune statistique fabriquée. N'écrivez pas "40 % plus rapide" ou "2 × plus fiable" à moins qu'un utilisateur n'ait explicitement utilisé un langage similaire. L'étape d'Auto-QA vérifie les pourcentages non cités.
3. Les noms des clusters doivent reprendre le langage des utilisateurs. Étudiez le tableau des anti-modèles à l'Étape 3.
4. Chaque titre et direction de copy publicitaire doit citer son cluster source. Format : [cluster: "nom-du-cluster"].
5. La Section 2 est toujours présente dans la sortie — même dégradée. Ne l'omettez jamais.
6. Aucun mot interdit dans les copies générées : puissant, robuste, fluide, innovant, révolutionnaire, optimiser, exploiter, révolutionner, transformer.

---

Étape 1 — Analyser l'entrée et détecter la plateforme

Acceptez une invite en langage naturel contenant une URL d'application. Extrayez l'URL.

Détection de plateforme :

• apps.apple.com → App Store
• play.google.com/store/apps/details?id= → Google Play
• Toute autre URL → arrêtez et répondez : "Veuillez fournir une URL directe d'App Store ou Google Play. Je ne peux pas analyser les avis provenant d'autres sources."

Extraction de l'identifiant (à faire avant d'exécuter le script) :

Plateforme	Ce qu'il faut extraire	Comment faire
App Store	app_id numérique	Chiffres après /id dans l'URL
App Store	country	Code à 2 lettres après apps.apple.com/ (ex. us, gb)
Google Play	package_name	Valeur du paramètre id= de la requête

Conservez les valeurs extraites — vous en aurez besoin pour le nom du fichier de sortie à l'Étape 7.

Si un product_context a été fourni dans l'invite (ce que fait leur propre produit), stockez-le — il servira à personnaliser la copie à l'Étape 5.

---

Étape 2 — Collecter les avis et les métadonnées

Exécutez le script de récupération complet :

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

(Remarque : Remplacez {tmpdir} par le répertoire temporaire de votre système d'exploitation, par exemple /tmp sur macOS/Linux ou C:\Temp sur Windows).

Ce script récupère à la fois les métadonnées de la description du store et les avis.

• App Store : API iTunes — gratuite, sans authentification. Les avis de l'App Store sont récupérés via le fil RSS public d'Apple. Certaines applications renvoient 0 avis en raison des limitations de l'API Apple — dans ce cas, le skill continue avec les données disponibles et enregistre un avertissement. Google Play est la voie principale prise en charge.
• Google Play : package google-play-scraper — gratuit, sans authentification

Si le script échoue, lisez l'erreur sur stderr. Causes courantes :

• Package non installé : exécutez pip install google-play-scraper
• Application introuvable : vérifiez que l'URL correspond à une fiche active et en ligne
• Erreur API Google Play : exécutez pip install --upgrade google-play-scraper et réessayez

Le script affiche la progression de la collecte sur stderr. Attendez la fin. Après la fin, lisez {tmpdir}/asr-raw.json et affichez le résumé de la collecte à l'utilisateur :

✓ Collecte terminée : [N] avis ([N] avis faibles 1–3★) depuis [plateforme]
  Période : [plus ancien] à [plus récent]
  Package : [iTunes API | google-play-scraper]

Vérifiez le code de sortie :

• Code 0 → collecte réussie, vérifiez metadata.store_description. S'il est null : notez-le — la Section 2 utilisera l'état dégradé. Passez à l'Étape 3.
• Code 1 → erreur (lisez le message sur stderr, transmettez-le à l'utilisateur, arrêtez)
• Code 2 → Passerelle 1 déclenchée (moins de 10 avis faibles trouvés)

Passerelle 1 — Arrêt pour signal faible : Si le script se termine avec le code 2, lisez le gate_message depuis {tmpdir}/asr-raw.json et transmettez-le textuellement à l'utilisateur. Ne passez pas à l'Étape 3. Ne produisez pas de brief partiel.

---

Étape 3 — Regroupement en clusters de réclamations

Chargez low_star_reviews depuis {tmpdir}/asr-raw.json.

Regroupez tous les avis faibles en 4 à 6 thèmes de réclamation nommés. Appliquez cette formule pour noter chaque avis :

poids_réclamation = (4 - note) × facteur_récence

facteur_récence :
  âge de l'avis ≤ 90 jours → 1.0
  âge de l'avis 91–365 jours → 0.7
  âge de l'avis > 365 jours → 0.4

âge de l'avis = (date d'aujourd'hui) − (champ date de l'avis) en jours.

score_cluster = somme des poids_réclamation pour tous les avis du cluster.

Nommage des clusters — règle critique :

Vous serez tenté d'utiliser des noms abstraits. Résistez. Utilisez le verbe et le nom exacts des avis.

❌ Abstrait (incorrect)	✅ Langage de l'utilisateur (correct)
"Problèmes de stabilité"	"Plante lors de l'exportation en PDF"
"Problèmes de synchronisation"	"Données perdues après la synchronisation entre téléphone et ordinateur"
"Friction de monétisation"	"Paywall apparaît après 3 jours, pas 14 comme promis"
"Dégradation des performances"	"L'application se fige à chaque fois que je recherche"
"Problèmes d'intégration"	"Je n'arrive pas à inviter un collègue"

Règles :

• Chaque avis appartient à exactement un cluster (attribuez-le à son thème dominant)
• Écartez tout cluster avec moins de 3 avis — enregistrez-le comme bruit
• Sélectionnez 3 à 4 citations textuelles par cluster : d'abord la note la plus faible, puis la plus récente

Passerelle 2 — Taille minimale de cluster : Après avoir écarté les clusters de moins de 3 avis, vérifiez combien de clusters restent.

Passerelle 3 — Drapeau de faible confiance : S'il reste moins de 3 clusters :

• NE vous arrêtez PAS. Continuez à produire le résultat.
• Ajoutez ceci en préambule de l'en-tête du brief immédiatement après les métadonnées de l'application :

  ⚠ FAIBLE CONFIANCE : Seulement [N] cluster(s) de réclamations atteignent le seuil d'évidence minimum (≥ 3 avis de support). La sortie reflète des données limitées. Envisagez un concurrent avec plus d'avis, ou élargissez le filtre de notation.

• Incluez les clusters de niveau Moyen dans la sortie (score ≥ 5)

Classification par niveau (pour le tableau de classement dans la Section 1) :

• Critique : score ≥ 60
• Élevé : score 15–59
• Moyen : score 5–14 (n'incluez que lorsque la Passerelle 3 s'applique)
• Bruit : score < 5 (écartez, n'incluez pas)

Écrivez les clusters dans {tmpdir}/asr-clusters.json :

{
  "clusters": [
    {
      "name": "nom du cluster dans le langage des utilisateurs",
      "score": 34.5,
      "tier": "Élevé",
      "review_count": 14,
      "verbatim_quotes": [
        {"rating": 1, "text": "mots exacts de l'utilisateur", "date": "YYYY-MM-DD"},
        ...
      ]
    }
  ],
  "discarded_noise": 2,
  "gate_3_triggered": false
}

---

Étape 4 — Détection des promesses non tenues

C'est l'étape qui distingue ce skill de tous les outils existants. Elle doit s'exécuter comme une étape distincte et nommée.

Chargez :

• metadata.store_description depuis {tmpdir}/asr-raw.json
• Tous les clusters depuis {tmpdir}/asr-clusters.json

Si store_description est null : Définissez store_description_available: false. Écrivez {tmpdir}/asr-promises.json avec un tableau broken_promises vide et detection_note comme spécifié ci-dessous. Passez à l'Étape 5.

Si la description du store est disponible :

1. Extrayez les affirmations. Une affirmation est toute assertion spécifique et vérifiable concernant le comportement de l'application. Consultez references/broken-promise.md pour la définition complète et des exemples. Excluez les superlatifs vagues, les descriptions d'équipe et les citations de presse.

2. Faites la corrélation croisée. Pour chaque affirmation, vérifiez tous les noms de clusters et les citations textuelles. Une contradiction existe lorsque le cluster documente directement l'échec du comportement promis (minimum 3 avis).

3. Produisez des enregistrements de promesses non tenues — un par contradiction confirmée :

   {
     "claim_text": "extrait textuel de la description du store",
     "complaint_cluster": "nom exact du cluster",
     "gap_label": "Affirme X ; les utilisateurs signalent Y",
     "evidence_count": 18
   }
   

Écrivez dans {tmpdir}/asr-promises.json :

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

États dégradés :

• Pas de description : store_description_available: false, detection_note: "Description du store indisponible (récupérée le YYYY-MM-DD, renvoyée vide). La comparaison de promesses non tenues ne peut pas être effectuée."
• Aucune contradiction : no_contradictions_found: true, detection_note: "Aucune promesse non tenue détectée. La description du store ne semble pas exagérer par rapport aux clusters de réclamations."

Consultez references/broken-promise.md pour les anti-modèles (ce qu'il NE faut PAS signaler).

---

Étape 5 — Générer la copie

À l'aide des clusters de l'Étape 3 et des promesses non tenues de l'Étape 4, générez les Sections 3 à 5 du brief.

Règles pour la copie (s'appliquent aux trois sections) :

• Chaque titre et direction doit citer son cluster source : [cluster: "nom-du-cluster"]
• Aucun mot interdit : puissant, robuste, fluide, innovant, révolutionnaire, optimiser, exploiter, révolutionner, transformer
• Aucune statistique fabriquée — pas de pourcentages ou de chiffres à moins qu'un utilisateur ne les ait utilisés
• Si product_context a été fourni : personnalisez les directions "Dites ceci" en fonction des fonctionnalités de ce produit. Sinon : écrivez comme des modèles de positionnement que l'utilisateur remplira.
• Utilisez le langage des utilisateurs dans les titres — dérivez-le ou citez le texte réel des avis

Section 3 — Banque de H1 pour page d'accueil (3 à 5 titres) :

• Chacun : "[texte du titre]" [cluster: "nom-du-cluster"]
• ≤ 8 mots si possible
• Adressez-vous directement à l'utilisateur frustré

Section 4 — Directions de copy publicitaire (exactement 3 paires) :

Cluster : [nom du cluster]
Pas ça : "[ce que prétend le concurrent ou une alternative générique faible]"
Dites ceci : "[contre-affirmation fondée sur les preuves de réclamations]"
Preuve : [N] utilisateurs ont signalé [résumé textuel de la réclamation]

Section 5 — Avertissements anti-affirmations :

• Un avertissement par promesse non tenue de l'Étape 4
• Si la Section 2 est dégradée : une seule note (consultez references/brief-format.md pour le texte exact)

---

Étape 6 — Auto-QA

Avant d'enregistrer, vérifiez le brief généré par rapport à ces contrôles. Si un contrôle échoue, corrigez l'élément spécifique et revérifiez — n'enregistrez pas un brief échouant.

Contrôle	Règle
Citations textuelles présentes	Chaque cluster a ≥ 2 citations textuelles
Aucun mot interdit	Aucun des 9 mots interdits n'apparaît dans les Sections 3 à 5
Aucun pourcentage non cité	Tout % dans la sortie doit provenir de mots réels d'un utilisateur
Toute copie citée	Chaque titre et "Dites ceci" a une citation [cluster: "nom"]
Nombre de clusters ≥ 1	Au moins un cluster a survécu aux Passerelles 2 et 3
Section 2 présente	La Section 2 apparaît dans la sortie (dans n'importe quel état)
Notes des citations ≤ 3	Toutes les citations textuelles proviennent d'avis 1–3★

Remarque sur le nombre de clusters : Le minimum pour un brief réussi est de 1 cluster (pas 3). Le drapeau de faible confiance de la Passerelle 3 gère les cas où moins de 3 clusters survivent — c'est un avertissement, pas un échec. L'Auto-QA échoue uniquement si 0 clusters existent.

---

Étape 7 — Enregistrer la sortie

Assemblez le brief complet selon le format dans references/brief-format.md.

Enregistrez dans :

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

Créez le répertoire docs/review-briefs/ s'il n'existe pas.

Imprimez le brief complet à l'utilisateur.

Nettoyez les fichiers temporaires : {tmpdir}/asr-raw.json, {tmpdir}/asr-clusters.json, {tmpdir}/asr-promises.json.