app-store-review-arbitrage
Converta a URL de um concorrente (App Store ou Google Play) em um briefing de GTM de uma sessão: clusters de reclamações ranqueados, um mapa de promessas quebradas, títulos para página inicial e direções para anúncios — tudo originado de avaliações literais.
Regras Críticas (leia antes do Passo 1)
Estas regras se aplicam a todos os passos. Violar qualquer uma delas falha na Auto-QA (Passo 6).
- Toda citação deve ser literal. Sem paráfrase, sem correção gramatical, sem limpeza. Apenas as palavras exatas do avaliador.
- Nenhuma estatística fabricada. Não escreva "40% mais rápido" ou "2× mais confiável" a menos que um avaliador tenha usado explicitamente uma linguagem semelhante. O passo de Auto-QA verifica porcentagens não citadas.
- Os nomes dos clusters devem usar a linguagem do avaliador. Estude a tabela de anti-padrões no Passo 3.
- Cada título e direção de anúncio deve citar seu cluster de origem. Formato:
[cluster: "nome-do-cluster"]. - A Seção 2 está sempre presente na saída — mesmo quando degradada. Nunca pule ou omita.
- Nenhuma palavra proibida em qualquer cópia gerada: poderoso, robusto, contínuo, inovador, revolucionário, simplificar, alavancar, revolucionar, transformar.
Passo 1 — Analisar Entrada e Detectar Plataforma
Aceite um prompt em linguagem natural contendo uma URL de aplicativo. Extraia a URL.
Detecção de plataforma:
apps.apple.com→ App Storeplay.google.com/store/apps/details?id=→ Google Play- Qualquer outra URL → pare e responda: "Por favor, forneça uma URL direta da App Store ou Google Play. Não consigo analisar dados de avaliações de outras fontes."
Extração de ID (faça isso antes de executar o script):
| Plataforma | O que extrair | Como |
|---|---|---|
| App Store | app_id numérico | Dígitos após /id na URL |
| App Store | country | Código de 2 letras após apps.apple.com/ (ex.: us, gb) |
| Google Play | package_name | Valor do parâmetro id= |
Persista os valores extraídos — você precisará deles para o nome do arquivo de saída no Passo 7.
Se product_context foi fornecido no prompt do usuário (o que o próprio produto deles faz), armazene-o — usado para personalizar a cópia no Passo 5.
Passo 2 — Coletar Avaliações e Metadados
Execute o script de coleta completo:
python3 scripts/fetch_reviews.py "{app_url}" --output {tmpdir}/asr-raw.json
(Nota: Substitua {tmpdir} pelo diretório temporário do seu sistema operacional, por exemplo, /tmp no macOS/Linux ou C:\Temp no Windows).
Isso busca tanto os metadados da descrição da loja quanto as avaliações.
- App Store: iTunes API — gratuito, sem autenticação. As avaliações da App Store são buscadas via feed público RSS da Apple. Alguns aplicativos retornam 0 avaliações devido às limitações da API da Apple — nesse caso, o skill continua com os dados disponíveis e registra um aviso. Google Play é o caminho principal suportado.
- Google Play: pacote
google-play-scraper— gratuito, sem autenticação
Se o script falhar, leia o erro do stderr. Causas comuns:
- Pacote não instalado: execute
pip install google-play-scraper - Aplicativo não encontrado: verifique se a URL é uma listagem atual e ativa
- Erro na API do Google Play: execute
pip install --upgrade google-play-scrapere tente novamente
O script imprimirá o progresso da coleta no stderr. Aguarde a conclusão. Após a conclusão, leia {tmpdir}/asr-raw.json e exiba o resumo da coleta para o usuário:
✓ Coletadas [N] avaliações ([N] com poucas estrelas 1–3★) do(a) [plataforma]
Intervalo de datas: [mais antiga] a [mais recente]
Pacote: [iTunes API | google-play-scraper]
Verifique o código de saída:
- Saída 0 → coleta bem-sucedida, verifique
metadata.store_description. Se nulo: anote isso — a Seção 2 usará o estado degradado. Prossiga para o Passo 3. - Saída 1 → erro (leia a mensagem de stderr, exiba-a para o usuário, pare)
- Saída 2 → Gate 1 acionado (< 10 avaliações com poucas estrelas encontradas)
Gate 1 — Parada por sinal baixo: Se o script sair com código 2, leia o gate_message de {tmpdir}/asr-raw.json e exiba-o literalmente para o usuário. Não prossiga para o Passo 3. Não produza um briefing parcial.
Passo 3 — Agrupamento de Reclamações
Carregue low_star_reviews de {tmpdir}/asr-raw.json.
Agrupe todas as avaliações com poucas estrelas em 4–6 temas de reclamação nomeados. Aplique esta fórmula para pontuar cada avaliação:
peso_reclamacao = (4 - avaliacao) × fator_recencia
fator_recencia:
idade da avaliacao ≤ 90 dias → 1,0
idade da avaliacao 91–365 dias → 0,7
idade da avaliacao > 365 dias → 0,4
idade da avaliacao = (data de hoje) − (campo date da avaliação) em dias.
pontuacao_cluster = soma de peso_reclamacao para todas as avaliações no cluster.
Nomeação de clusters — regra crítica:
Você vai querer escrever nomes abstratos. Resista. Use o verbo e substantivo exatos das avaliações.
| ❌ Abstraído (errado) | ✅ Linguagem do avaliador (correto) |
|---|---|
| "Problemas de estabilidade" | "Falha ao exportar para PDF" |
| "Problemas de sincronização" | "Dados perdidos após sincronização entre celular e desktop" |
| "Atrito de monetização" | "Paywall aparece após 3 dias, não 14 como prometido" |
| "Degradação de desempenho" | "O aplicativo congela toda vez que pesquiso" |
| "Problemas de integração" | "Não consigo descobrir como convidar um colega" |
Regras:
- Cada avaliação pertence a exatamente um cluster (atribua ao seu tema dominante)
- Descarte qualquer cluster com menos de 3 avaliações — registre-o como ruído
- Selecione 3–4 citações literais por cluster: menor classificação de estrelas primeiro, depois a mais recente
Gate 2 — Tamanho mínimo do cluster: Após descartar clusters com menos de 3 avaliações, verifique quantos clusters restam.
Gate 3 — Sinalizador de baixa confiança: Se restarem menos de 3 clusters:
- NÃO pare. Continue para a saída.
- Anteponha isso ao cabeçalho do briefing imediatamente após os metadados do aplicativo:
⚠ BAIXA CONFIANÇA: Apenas [N] cluster(s) de reclamação atenderam ao limite mínimo de evidência (≥ 3 avaliações de suporte). A saída reflete dados limitados. Considere um concorrente com mais avaliações, ou amplie o filtro de classificação.
- Inclua clusters de nível Médio na saída (pontuação ≥ 5)
Classificação por nível (para a tabela de classificação na Seção 1):
- Crítico: pontuação ≥ 60
- Alto: pontuação 15–59
- Médio: pontuação 5–14 (inclua apenas quando o Gate 3 se aplicar)
- Ruído: pontuação < 5 (descarte, não inclua)
Escreva clusters em {tmpdir}/asr-clusters.json:
{
"clusters": [
{
"name": "nome do cluster na linguagem do avaliador",
"score": 34.5,
"tier": "Alto",
"review_count": 14,
"verbatim_quotes": [
{"rating": 1, "text": "palavras exatas do avaliador", "date": "YYYY-MM-DD"},
...
]
}
],
"discarded_noise": 2,
"gate_3_triggered": false
}
Passo 4 — Detecção de Promessas Não Cumpridas
Este é o passo que diferencia este skill de todas as ferramentas existentes. Deve ser executado como um passo nomeado e distinto.
Carregue:
metadata.store_descriptionde{tmpdir}/asr-raw.json- Todos os clusters de
{tmpdir}/asr-clusters.json
Se store_description for nulo: Defina store_description_available: false. Escreva {tmpdir}/asr-promises.json com array broken_promises vazio e detection_note conforme especificado abaixo. Prossiga para o Passo 5.
Se a descrição da loja estiver disponível:
-
Extraia alegações. Uma alegação é qualquer afirmação específica e testável sobre o comportamento do aplicativo. Consulte
references/broken-promise.mdpara a definição completa e exemplos. Exclua superlativos vagos, descrições de equipe e citações de imprensa. -
Referência cruzada. Para cada alegação, verifique todos os nomes de clusters e citações literais. Existe uma contradição quando o cluster documenta diretamente a falha do comportamento prometido (mínimo de 3 avaliações).
-
Produza registros de promessa não cumprida — um por contradição confirmada:
{ "claim_text": "trecho literal da descrição da loja", "complaint_cluster": "nome exato do cluster", "gap_label": "Alega X; usuários relatam Y", "evidence_count": 18 }
Escreva em {tmpdir}/asr-promises.json:
{
"store_description_available": true,
"broken_promises": [...],
"no_contradictions_found": false,
"detection_note": null
}
Estados degradados:
- Sem descrição:
store_description_available: false,detection_note: "Descrição da loja indisponível (buscada em YYYY-MM-DD, retornou vazia). A comparação de promessas não cumpridas não pode ser realizada." - Sem contradições:
no_contradictions_found: true,detection_note: "Nenhuma promessa não cumprida detectada. A descrição da loja não parece exagerar em relação aos clusters de reclamação."
Consulte references/broken-promise.md para anti-padrões (o que NÃO sinalizar).
Passo 5 — Gerar Cópia
Usando clusters do Passo 3 e promessas não cumpridas do Passo 4, gere as Seções 3–5 do briefing.
Regras de cópia (aplicam-se a todas as três seções):
- Cada título e direção deve citar seu cluster de origem:
[cluster: "nome-do-cluster"] - Sem palavras proibidas: poderoso, robusto, contínuo, inovador, revolucionário, simplificar, alavancar, revolucionar, transformar
- Nenhuma estatística fabricada — sem porcentagens ou números, a menos que um avaliador os tenha usado
- Se
product_contextfoi fornecido: torne as direções "Diga isto" específicas para os recursos desse produto. Se não: escreva como modelos de posicionamento que o usuário preenche. - Use a linguagem do avaliador nos títulos — derive ou cite o texto real da avaliação
Seção 3 — Banco de H1 para Página Inicial (3–5 títulos):
- Cada um:
"[texto do título]" [cluster: "nome-do-cluster"] - ≤ 8 palavras quando possível
- Aborde diretamente o usuário frustrado
Seção 4 — Direções de Cópia de Anúncios (exatamente 3 pares):
Cluster: [nome do cluster]
Não isso: "[o que o concorrente alega ou uma alternativa genérica fraca]"
Diga isto: "[contra-alegação fundamentada na evidência da reclamação]"
Evidência: [N] avaliadores relataram [resumo literal da reclamação]
Seção 5 — Avisos de Contra-Alegação:
- Um aviso por promessa não cumprida do Passo 4
- Se a Seção 2 estiver degradada: nota única (consulte
references/brief-format.mdpara o texto exato)
Passo 6 — Auto-QA
Antes de salvar, verifique o briefing gerado em relação a estas verificações. Se alguma verificação falhar, corrija o item específico e reverifique — não salve um briefing com falha.
| Verificação | Regra |
|---|---|
| Citações literais presentes | Cada cluster tem ≥ 2 citações literais |
| Nenhuma palavra proibida | Nenhuma das 9 palavras proibidas aparece nas Seções 3–5 |
| Nenhuma porcentagem não citada | Qualquer % na saída deve ser rastreável até as palavras reais de um avaliador |
| Toda cópia citada | Cada título e "Diga isto" tem uma citação [cluster: "nome"] |
| Contagem de clusters ≥ 1 | Pelo menos um cluster sobreviveu aos Gates 2/3 |
| Seção 2 presente | A Seção 2 aparece na saída (em qualquer estado) |
| Classificações de citações ≤ 3 | Todas as citações literais vieram de avaliações de 1–3★ |
Nota sobre a contagem de clusters: O mínimo para um briefing aprovado é 1 cluster (não 3). O sinalizador de baixa confiança do Gate 3 lida com casos em que < 3 clusters sobrevivem — isso é um aviso, não uma falha. A Auto-QA falha apenas se 0 clusters existirem.
Passo 7 — Salvar Saída
Monte o briefing completo de acordo com o formato em references/brief-format.md.
Salve em:
docs/review-briefs/[app-id]-[YYYY-MM-DD].md
Crie o diretório docs/review-briefs/ se ele não existir.
Imprima o briefing completo para o usuário.
Limpe os arquivos temporários: {tmpdir}/asr-raw.json, {tmpdir}/asr-clusters.json, {tmpdir}/asr-promises.json.