arbitraje-de-reseñas-de-apps
Convierte la URL de la App Store o Google Play de un competidor en un brief de GTM en una sola sesión: grupos de quejas clasificados, un mapa de promesas incumplidas, titulares para páginas de aterrizaje y direcciones de copia publicitaria, todo basado en reseñas textuales.
Reglas Críticas (leer antes del Paso 1)
Estas reglas se aplican a lo largo de todos los pasos. Violar cualquiera de ellas falla la Autoevaluación (Paso 6).
- Cada cita debe ser textual. Sin paráfrasis, sin corrección gramatical, sin limpieza. Solo las palabras exactas del revisor.
- Sin estadísticas inventadas. No escribas "40% más rápido" o "2× más confiable" a menos que un revisor haya usado explícitamente un lenguaje similar. El paso de Autoevaluación verifica que no haya porcentajes sin citar.
- Los nombres de los grupos deben usar el lenguaje del revisor. Estudia la tabla de anti-patrones en el Paso 3.
- Cada titular y dirección de copia publicitaria debe citar su grupo de origen. Formato:
[cluster: "nombre-del-grupo"]. - La Sección 2 siempre está presente en la salida, incluso degradada. Nunca la saltes ni la omitas.
- Sin palabras prohibidas en ninguna copia generada: potente, robusto, perfecto, innovador, revolucionario, agilizar, aprovechar, revolucionar, transformar.
Paso 1 — Analizar Entrada y Detectar Plataforma
Acepta un aviso en lenguaje natural que contenga una URL de aplicación. Extrae la URL.
Detección de plataforma:
apps.apple.com→ App Storeplay.google.com/store/apps/details?id=→ Google Play- Cualquier otra URL → detente y responde: "Proporciona una URL directa de App Store o Google Play. No puedo analizar datos de reseñas de otras fuentes."
Extracción de ID (haz esto antes de ejecutar el script):
| Plataforma | Qué extraer | Cómo |
|---|---|---|
| App Store | app_id numérico | Dígitos después de /id en la URL |
| App Store | country | Código de 2 letras después de apps.apple.com/ (ej., us, gb) |
| Google Play | package_name | Valor del parámetro de consulta id= |
Persiste los valores extraídos; los necesitarás para el nombre del archivo de salida en el Paso 7.
Si se proporcionó product_context en el aviso del usuario (qué hace su propio producto), guárdalo; se usa para personalizar la copia en el Paso 5.
Paso 2 — Recopilar Reseñas y Metadatos
Ejecuta el script de recopilación completo:
python3 scripts/fetch_reviews.py "{app_url}" --output {tmpdir}/asr-raw.json
(Nota: Reemplaza {tmpdir} con el directorio temporal de tu sistema operativo, ej., /tmp en macOS/Linux o C:\Temp en Windows).
Esto obtiene tanto la descripción de la tienda como las reseñas.
- App Store: API de iTunes — gratis, sin autenticación. Las reseñas de App Store se obtienen a través del feed RSS público de iTunes de Apple. Algunas aplicaciones devuelven 0 reseñas debido a limitaciones de la API de Apple; en ese caso, el skill continúa con los datos disponibles y registra una advertencia. Google Play es la ruta principal compatible.
- Google Play: paquete
google-play-scraper— gratis, sin autenticación
Si el script falla, lee el error de stderr. Causas comunes:
- Paquete no instalado: ejecuta
pip install google-play-scraper - Aplicación no encontrada: verifica que la URL sea un listado actual y activo
- Error de API de Google Play: ejecuta
pip install --upgrade google-play-scrapery reintenta
El script imprimirá el progreso de la recopilación en stderr. Espera a que termine. Después de la finalización, lee {tmpdir}/asr-raw.json y muestra el resumen de recopilación al usuario:
✓ Recopiladas [N] reseñas ([N] de baja calificación 1–3★) de [plataforma]
Rango de fechas: [más antigua] a [más reciente]
Paquete: [iTunes API | google-play-scraper]
Verifica el código de salida:
- Salida 0 → recopilación exitosa, verifica
metadata.store_description. Si es nulo: anótalo — la Sección 2 usará el estado degradado. Procede al Paso 3. - Salida 1 → error (lee el mensaje de stderr, muéstralo al usuario, detente)
- Salida 2 → Puerta 1 activada (< 10 reseñas de baja calificación encontradas)
Puerta 1 — Parada por señal baja: Si el script sale con el código 2, lee gate_message de {tmpdir}/asr-raw.json y muéstralo al usuario textualmente. No procedas al Paso 3. No produzcas un brief parcial.
Paso 3 — Agrupación de Quejas
Carga low_star_reviews de {tmpdir}/asr-raw.json.
Agrupa todas las reseñas de baja calificación en 4–6 temas de queja nombrados. Aplica esta fórmula para puntuar cada reseña:
peso_queja = (4 - calificación) × factor_actualidad
factor_actualidad:
antigüedad reseña ≤ 90 días → 1.0
antigüedad reseña 91–365 días → 0.7
antigüedad reseña > 365 días → 0.4
antigüedad reseña = (fecha de hoy) − (campo date de la reseña) en días.
puntaje_grupo = suma de peso_queja para todas las reseñas en el grupo.
Nombrado de grupos — regla crítica:
Querrás escribir nombres abstractos. Resiste. Usa el verbo exacto y el sustantivo de las reseñas.
| ❌ Abstracto (incorrecto) | ✅ Lenguaje del revisor (correcto) |
|---|---|
| "Problemas de estabilidad" | "Se bloquea al exportar a PDF" |
| "Problemas de sincronización" | "Datos perdidos después de sincronizar entre teléfono y escritorio" |
| "Fricción de monetización" | "El muro de pago aparece después de 3 días, no 14 como prometieron" |
| "Degradación del rendimiento" | "La aplicación se congela cada vez que busco" |
| "Problemas de incorporación" | "No puedo entender cómo invitar a un compañero de equipo" |
Reglas:
- Cada reseña pertenece exactamente a un grupo (asígnale su tema dominante)
- Descarta cualquier grupo con menos de 3 reseñas — regístralo como ruido
- Selecciona 3–4 citas textuales por grupo: la calificación más baja primero, luego la más reciente
Puerta 2 — Tamaño mínimo del grupo: Después de descartar grupos con menos de 3 reseñas, verifica cuántos grupos quedan.
Puerta 3 — Bandera de baja confianza: Si quedan menos de 3 grupos:
- NO te detengas. Continúa con la salida.
- Antepón esto al encabezado del brief inmediatamente después de los metadatos de la aplicación:
⚠ BAJA CONFIANZA: Solo [N] grupo(s) de quejas cumplió el umbral mínimo de evidencia (≥ 3 reseñas de apoyo). La salida refleja datos limitados. Considera un competidor con más reseñas o amplía el filtro de calificación.
- Incluye grupos de nivel Medio en la salida (puntaje ≥ 5)
Clasificación por niveles (para la tabla de clasificación en la Sección 1):
- Crítico: puntaje ≥ 60
- Alto: puntaje 15–59
- Medio: puntaje 5–14 (incluir solo cuando se aplique la Puerta 3)
- Ruido: puntaje < 5 (descartar, no incluir)
Escribe los grupos en {tmpdir}/asr-clusters.json:
{
"clusters": [
{
"name": "nombre del grupo en lenguaje del revisor",
"score": 34.5,
"tier": "Alto",
"review_count": 14,
"verbatim_quotes": [
{"rating": 1, "text": "palabras exactas del revisor", "date": "YYYY-MM-DD"},
...
]
}
],
"discarded_noise": 2,
"gate_3_triggered": false
}
Paso 4 — Detección de Promesas Incumplidas
Este es el paso que diferencia este skill de cualquier herramienta existente. Debe ejecutarse como un paso distinto y nombrado.
Carga:
metadata.store_descriptionde{tmpdir}/asr-raw.json- Todos los grupos de
{tmpdir}/asr-clusters.json
Si store_description es nulo: Establece store_description_available: false. Escribe {tmpdir}/asr-promises.json con un array broken_promises vacío y detection_note como se especifica a continuación. Procede al Paso 5.
Si la descripción de la tienda está disponible:
-
Extrae afirmaciones. Una afirmación es cualquier aseveración específica y comprobable sobre el comportamiento de la aplicación. Consulta
references/broken-promise.mdpara la definición completa y ejemplos. Excluye superlativos vagos, descripciones del equipo y citas de prensa. -
Referencia cruzada. Para cada afirmación, verifica todos los nombres de grupos y citas textuales. Existe una contradicción cuando el grupo documenta directamente el fallo del comportamiento prometido (mínimo 3 reseñas).
-
Produce registros de promesas incumplidas — uno por cada contradicción confirmada:
{
"claim_text": "extracto textual de la descripción de la tienda",
"complaint_cluster": "nombre exacto del grupo",
"gap_label": "Afirma X; los usuarios reportan Y",
"evidence_count": 18
}
Escribe en {tmpdir}/asr-promises.json:
{
"store_description_available": true,
"broken_promises": [...],
"no_contradictions_found": false,
"detection_note": null
}
Estados degradados:
- Sin descripción:
store_description_available: false,detection_note: "Descripción de la tienda no disponible (obtenida el YYYY-MM-DD, devolvió vacío). No se puede realizar la comparación de promesas incumplidas." - Sin contradicciones:
no_contradictions_found: true,detection_note: "No se detectaron promesas incumplidas. La descripción de la tienda no parece exagerar en relación con los grupos de quejas."
Consulta references/broken-promise.md para anti-patrones (qué NO marcar).
Paso 5 — Generar Copia
Usando los grupos del Paso 3 y las promesas incumplidas del Paso 4, genera las Secciones 3–5 del brief.
Reglas de copia (aplican a las tres secciones):
- Cada titular y dirección debe citar su grupo de origen:
[cluster: "nombre-del-grupo"] - Sin palabras prohibidas: potente, robusto, perfecto, innovador, revolucionario, agilizar, aprovechar, revolucionar, transformar
- Sin estadísticas inventadas — sin porcentajes ni números a menos que un revisor los haya usado
- Si se proporcionó
product_context: haz que las direcciones "Di esto" sean específicas de las características de ese producto. Si no: escríbelas como plantillas de posicionamiento que el usuario completa. - Usa el lenguaje del revisor en los titulares — derívalos de o cita el texto real de la reseña
Sección 3 — Banco de H1 para Página de Aterrizaje (3–5 titulares):
- Cada uno:
"[texto del titular]" [cluster: "nombre-del-grupo"] - ≤ 8 palabras cuando sea posible
- Dirígete directamente al usuario frustrado
Sección 4 — Direcciones de Copia Publicitaria (exactamente 3 pares):
Grupo: [nombre del grupo]
No eso: "[lo que afirma el competidor o una alternativa genérica débil]"
Di esto: "[contra-afirmación basada en la evidencia de la queja]"
Evidencia: [N] revisores reportaron [resumen textual de la queja]
Sección 5 — Advertencias Anti-Afirmación:
- Una advertencia por cada promesa incumplida del Paso 4
- Si la Sección 2 está degradada: una sola nota (consulta
references/brief-format.mdpara la redacción exacta)
Paso 6 — Autoevaluación
Antes de guardar, verifica el brief generado contra estas comprobaciones. Si alguna comprobación falla, corrige el elemento específico y vuelve a verificar; no guardes un brief que falle.
| Comprobación | Regla |
|---|---|
| Citas textuales presentes | Cada grupo tiene ≥ 2 citas textuales |
| Sin palabras prohibidas | Ninguna de las 9 palabras prohibidas aparece en las Secciones 3–5 |
| Sin porcentajes sin citar | Cualquier % en la salida debe rastrearse a las palabras reales de un revisor |
| Toda la copia citada | Cada titular y "Di esto" tiene una cita [cluster: "nombre"] |
| Número de grupos ≥ 1 | Al menos un grupo sobrevivió a las Puertas 2/3 |
| Sección 2 presente | La Sección 2 aparece en la salida (en cualquier estado) |
| Calificaciones de citas ≤ 3 | Todas las citas textuales provinieron de reseñas de 1–3★ |
Nota sobre el número de grupos: El mínimo para un brief aprobado es 1 grupo (no 3). La bandera de baja confianza de la Puerta 3 maneja los casos donde < 3 grupos sobreviven — eso es una advertencia, no un fallo. La Autoevaluación falla solo si existen 0 grupos.
Paso 7 — Guardar Salida
Ensambla el brief completo según el formato en references/brief-format.md.
Guarda en:
docs/review-briefs/[app-id]-[YYYY-MM-DD].md
Crea el directorio docs/review-briefs/ si no existe.
Imprime el brief completo al usuario.
Limpia los archivos temporales: {tmpdir}/asr-raw.json, {tmpdir}/asr-clusters.json, {tmpdir}/asr-promises.json.