@saulwade/swl-ses 1.0.0

package/habilidades/orquestacion-async/SKILL.md

@@ -0,0 +1,303 @@
+---
+name: orquestacion-async
+description: >
+  Patrones de orquestación asíncrona para agentes: subagentes fire-and-forget,
+  gestión de tareas paralelas, corrección mid-task y supervisión no-bloqueante.
+  Basado en Deep Agents v0.5 (LangChain). Cargar cuando orquestador-swl necesite
+  ejecutar implementaciones en paralelo o gestionar agentes de larga duración.
+version: "1.1.0"
+evolved: true
+evolved-from: "1.0.0"
+evolved-at: "2026-04-24"
+evolved-by: "aprender"
+evolved-note: "Sección nueva: matriz agente × archivo con intersección vacía antes de lanzar paralelos"
+herramientasPermitidas: [Read]
+user-invocable: false
+exclusiones:
+  - "No cargar para concurrencia Python pura con asyncio/aiohttp — si la tarea es I/O concurrente en código de aplicación (no orquestación de agentes SWL), cargar `async-python`."
+  - "No cargar para lanzar un solo agente secuencialmente — el overhead de las 5 herramientas de gestión solo vale si hay ≥2 agentes en paralelo o una tarea de larga duración que bloquea el supervisor."
+  - "No cargar para delegar un slice a un subagente sin necesidad de supervisión ni corrección mid-task — para delegación simple sin monitoreo, el orquestador puede invocar el agente directamente sin este patrón."
+  - "No cargar para pipelines de datos o ETL con pasos dependientes — los patrones fire-and-forget asumen independencia entre tareas; para pipelines ordenados con dependencias usar `datos-etl`."
+evolvable: true  # default para skill estandar
+---
+# Orquestación Asíncrona de Agentes
+
+Patrones para supervisión no-bloqueante de subagentes, basados en Deep Agents v0.5
+y adaptados al sistema de delegación de swl-ses.
+
+## Cuándo NO cargar
+
+- La tarea es concurrencia Python con asyncio/aiohttp (no agentes SWL) — cargar `async-python`.
+- Se lanza un solo agente secuencialmente sin necesidad de supervisión — la delegación directa es más simple.
+- El pipeline tiene pasos con dependencias ordenadas — para ETL con dependencias cargar `datos-etl`.
+
+## Cuándo cargar
+
+- `orquestador-swl` necesita lanzar múltiples implementaciones en paralelo
+- Una tarea toma más de 3 minutos y bloquea la interacción con el usuario
+- Se necesita corrección mid-task de un agente en ejecución
+- Gestión de múltiples agentes concurrentes con diferentes prioridades
+
+## Principio fundamental
+
+> Un supervisor NUNCA debe bloquearse esperando a un subagente de larga duración.
+> El supervisor debe poder: responder al usuario, lanzar más tareas, verificar
+> progreso, y corregir el rumbo — todo mientras los subagentes trabajan.
+
+## Patrón: 5 herramientas de gestión async
+
+Inspirado en el modelo de Deep Agents v0.5:
+
+### 1. `start_async_task` — Lanzar tarea
+```
+Entrada: { agente, prompt, prioridad, timeout }
+Salida:  { taskId, estado: "en_progreso" }
+```
+El supervisor recibe un ID de tarea inmediatamente y continúa operando.
+
+### 2. `check_async_task` — Verificar estado
+```
+Entrada: { taskId }
+Salida:  { estado, progreso, resultado_parcial, errores }
+```
+Polling ligero — no bloquea, retorna estado actual.
+
+### 3. `update_async_task` — Corrección mid-task
+```
+Entrada: { taskId, instrucciones_adicionales }
+Salida:  { aceptado: true/false }
+```
+Envía instrucciones de corrección al subagente en ejecución.
+Solo funciona si el subagente está en estado "en_progreso".
+
+### 4. `cancel_async_task` — Cancelar tarea
+```
+Entrada: { taskId, razon }
+Salida:  { cancelado: true, trabajo_parcial }
+```
+Cancela un subagente y recupera trabajo parcial.
+
+### 5. `list_async_tasks` — Listar tareas
+```
+Entrada: { filtro_estado? }
+Salida:  [{ taskId, agente, estado, inicio, duracion }]
+```
+Vista general de todas las tareas gestionadas.
+
+## Estados de una tarea async
+
+```
+                    ┌─────────────┐
+                    │   creada    │
+                    └──────┬──────┘
+                           │ start
+                    ┌──────▼──────┐
+            ┌───── │ en_progreso  │ ─────┐
+            │      └──────┬──────┘      │
+      update│             │             │ cancel
+            │      ┌──────▼──────┐      │
+            └────► │   exitosa   │      │
+                   └─────────────┘      │
+                   ┌──────▼──────┐      │
+                   │   fallida   │ ◄────┘
+                   └─────────────┘
+                   ┌─────────────┐
+                   │  cancelada  │
+                   └─────────────┘
+```
+
+## Implementación en swl-ses
+
+### Mapeo a herramientas existentes
+
+| Herramienta async | Implementación swl-ses |
+|-------------------|----------------------|
+| `start_async_task` | `Agent()` con `run_in_background: true` |
+| `check_async_task` | Verificar notificación de agente completado |
+| `update_async_task` | `SendMessage` al agente con `to: agentId` |
+| `cancel_async_task` | No disponible nativamente — requiere convención |
+| `list_async_tasks` | `task-service.js` (hooks/lib/) |
+
+### Patrón de uso en orquestador-swl
+
+```markdown
+## Fase de implementación paralela
+
+1. Analizar el plan e identificar slices independientes
+2. Para cada slice independiente:
+   - Lanzar Agent() con run_in_background: true
+   - Registrar taskId en task-service.js
+3. Mientras los agentes trabajan:
+   - Responder al usuario sobre progreso
+   - Revisar resultados parciales si llegan notificaciones
+   - Lanzar nuevos agentes si hay más slices listos
+4. Cuando todos completen:
+   - Verificar resultados con revisor-codigo-swl
+   - Resolver conflictos si dos agentes tocaron los mismos archivos
+```
+
+### Corrección mid-task
+
+Cuando un agente en background necesita ajuste:
+
+```markdown
+1. Detectar desviación (por notificación o verificación manual)
+2. Enviar SendMessage al agentId con instrucciones de corrección:
+   - "El endpoint cambió de /api/v1/users a /api/v2/users"
+   - "Usar SQLAlchemy async, no sync"
+3. El agente recibe la corrección en su contexto y ajusta
+```
+
+### Resolución de conflictos
+
+Cuando dos agentes modifican el mismo archivo:
+
+```
+1. Detectar conflicto: edit-accumulator.js registra archivos tocados
+2. Si hay solapamiento:
+   a. Revisar diffs de ambos agentes
+   b. Determinar si son complementarios o contradictorios
+   c. Complementarios → merge manual o automático
+   d. Contradictorios → escalar al usuario con ambas versiones
+3. Nunca aplicar ciegamente el último cambio
+```
+
+## Límites y restricciones
+
+### De swl-ses
+- `MAX_DEPTH = 2` — Un agente puede delegar, pero el delegado no puede delegar
+- `max_concurrent_children = 3` — Máximo 3 subagentes concurrentes (configurable)
+- Agentes delegados NO escriben a memoria compartida (MEMORY.md)
+- Agentes delegados NO interactúan con el usuario directamente
+
+### Del runtime (Claude Code)
+- Background agents notifican al completar — no hay polling periódico
+- El contexto del agente padre no ve los tool calls internos del hijo
+- SendMessage requiere el agentId exacto retornado por Agent()
+
+## Escenarios de uso
+
+### Escenario A: Feature con frontend + backend + tests
+```
+orquestador-swl:
+  1. Lanza backend-api-swl (Agent, background) → taskId_1
+  2. Lanza frontend-react-swl (Agent, background) → taskId_2
+  3. Espera notificaciones
+  4. Backend completa → lanza tdd-qa-swl para tests de API → taskId_3
+  5. Frontend completa → lanza tdd-qa-swl para tests de UI → taskId_4
+  6. Todos completan → revisor-codigo-swl verifica todo junto
+```
+
+### Escenario B: Refactoring paralelo
+```
+orquestador-swl:
+  1. Divide módulos a refactorizar en grupos independientes
+  2. Lanza N agentes en paralelo (máx 3)
+  3. Cuando completa un grupo → verifica y lanza el siguiente
+  4. Al final → merge + test completo
+```
+
+### Escenario C: Investigación + implementación
+```
+orquestador-swl:
+  1. Lanza investigador-swl (background) para research
+  2. Mientras, prepara scaffold básico directamente
+  3. Investigador completa → lee resultados
+  4. Lanza implementador-swl con contexto del research
+```
+
+## Métricas de eficiencia
+
+| Métrica | Fórmula | Objetivo |
+|---------|---------|----------|
+| Paralelismo efectivo | Tiempo secuencial / Tiempo real | ≥ 2.0x |
+| Conflictos por tarea | Archivos con conflicto / Total archivos | ≤ 5% |
+| Reintentos por corrección | Correcciones mid-task / Total tareas | ≤ 20% |
+| Overhead de orquestación | Tokens orquestador / Tokens total | ≤ 15% |
+
+## Gotchas / Errores comunes no obvios
+
+- **`check_task_status` retorna `completada` pero el archivo generado por el subagente no existe en disco**: el subagente reportó éxito pero terminó antes de escribir el archivo por una excepción silenciada. Causa: el estado `completada` en el patrón de 5 herramientas refleja que el subagente terminó su ejecución sin lanzar excepción al supervisor — si el error fue interno y capturado silenciosamente, el output no existe aunque el estado sea correcto. Solución: la herramienta `get_task_result` debe verificar explícitamente que los artefactos de output existen antes de reportar `completada`; agregar validación de postcondición: `assert Path(archivo_esperado).exists()`.
+- **Lanzar 8 subagentes en paralelo con `start_async_task` sin semáforo consume el presupuesto de tokens del orquestador en segundos**: cada invocación de subagente consume el contexto del orquestador mientras espera resultados de todos ellos. Causa: el patrón fire-and-forget no limita la concurrencia — 8 agentes en paralelo pueden disparar 8× el costo esperado si el supervisor los monitorea activamente. Solución: limitar con un semáforo de concurrencia máxima de 3-4 agentes simultáneos, y usar `check_task_status` con backoff para no encuestar continuamente.
+- **Corrección mid-task con `modify_task_prompt` produce un subagente que ignora la corrección y continúa con el plan original**: el subagente ya tiene el plan congelado en su contexto y la corrección llega como un mensaje adicional que no modifica el plan original. Causa: `modify_task_prompt` agrega instrucciones al contexto del agente pero si el plan ya está en ejecución, el subagente puede priorizarlo sobre las instrucciones nuevas. Solución: la corrección mid-task debe ser explícita sobre qué cambiar: en lugar de agregar "también haz X", indicar "STOP el paso actual, cambia a Y" con autoridad clara sobre el paso en conflicto.
+- **`cancel_task` no libera los archivos que el subagente dejó en estado parcial**: cancelar una tarea detiene el agente pero los archivos que ya escribió permanecen con contenido incompleto. Causa: el patrón de cancelación no tiene rollback de los artefactos ya generados — solo detiene la ejecución futura. Solución: antes de `cancel_task`, registrar los archivos que el subagente está modificando (via `check_task_status` que devuelve `archivos_en_progreso`), y después de la cancelación, revertir esos archivos con `git checkout -- archivos` si el trabajo no es recuperable.
+
+---
+
+## Matriz agente × archivo: partición explícita antes de lanzar paralelos
+
+### Regla
+
+Antes de lanzar **N agentes en paralelo** que modifican archivos, producir una
+**matriz explícita** agente × archivo con **intersección vacía** entre filas.
+Un archivo compartido por 2 agentes paralelos produce merge silencioso
+impredecible: el último write gana, sin detección ni log.
+
+### Por qué
+
+Los agentes fire-and-forget no tienen coordinación entre sí. Si el agente A
+está editando `core/service.py` y el agente B también, la secuencia real es:
+
+1. A lee versión V0, piensa, escribe V1.
+2. B lee versión V0 (no V1), piensa, escribe V2.
+3. Resultado: los cambios de A desaparecen. Git no muestra conflicto porque
+   B ya "reconcilió" en su cabeza el archivo.
+
+El patrón no se detecta por tests unitarios aislados. Solo se observa al leer
+el diff final contra lo esperado — y suele descubrirse horas después.
+
+### Patrón canónico: matriz explícita pre-lanzamiento
+
+```markdown
+## Matriz de partición — Sprint X
+
+| Agente | Archivos (exclusivos) |
+|--------|----------------------|
+| backend-python-swl | api/routers/emaia.py, core/service_usuarios.py |
+| frontend-react-swl | ui/pages/usuarios.tsx, ui/components/FormUsuario.tsx |
+| datos-swl | core/db/models.py, alembic/versions/00XX_usuarios.py |
+| tdd-qa-swl | tests/integration/test_usuarios.py (solo lectura en el resto) |
+
+Verificación: intersección de archivos entre filas = ∅.
+Archivos no listados: NO se tocan en este sprint.
+```
+
+### Protocolo operativo
+
+1. **Antes de invocar agentes en paralelo**, el orquestador escribe la matriz
+   en `.planning/sprint-X/matriz-agentes.md` o equivalente.
+2. **Cada agente delegado recibe explícitamente** su lista de archivos en
+   el prompt de delegación: `"Tus archivos asignados son X, Y, Z. No tocar
+   ningún otro archivo sin escalar al orquestador."`.
+3. **Si un agente necesita tocar un archivo no asignado**, debe escalar
+   (pausar y reportar), no tomar decisión unilateral.
+4. **Post-ejecución**: verificar que el diff de cada agente está contenido
+   en sus archivos asignados. Un agente que tocó un archivo ajeno es señal
+   de drift del scope y debe revertirse.
+
+### Casos donde NO aplica
+
+- **Tareas de un solo agente** (serial): la matriz es innecesaria.
+- **Lecturas sin writes**: múltiples agentes pueden leer el mismo archivo
+  en paralelo sin riesgo; la matriz aplica a writes.
+- **Archivos append-only con locking** (JSONL con `fs.appendFileSync`):
+  los appends atómicos no se pisan. Documentar explícitamente estos casos.
+
+### Anti-patrón
+
+```markdown
+# MAL — delegación sin partición
+"Lanzar backend-python-swl, frontend-react-swl y datos-swl en paralelo
+ para implementar la feature X."
+
+# Cada agente descubre por sí mismo qué archivos toca. Garantizado:
+# los 3 tocan `core/schemas.py` porque todos necesitan el tipo Usuario.
+```
+
+### Relacionado
+
+- `checkpoints-verificacion` — cómo pausar agentes en checkpoints HITL.
+- `git-worktrees-paralelo` — aislamiento físico con worktrees cuando la
+  matriz no se puede diseñar con intersección vacía.
+- Regla en CLAUDE.md: "Matriz agente × archivo antes de lanzar paralelos
+  N≥3" — consolidar como regla del proyecto si el patrón se repite.

package/habilidades/paid-media-tracking/SKILL.md

@@ -0,0 +1,269 @@
+---
+name: paid-media-tracking
+description: >
+  Implementación técnica de herramientas para campañas de publicidad pagada:
+  Google Ads API, análisis de search terms, conversión tracking server-side,
+  auditoría de cuentas programática y dashboards de rendimiento. Cargar cuando
+  se construya una integración con Google Ads API, se implemente análisis
+  automático de search terms, se diseñe un sistema de medición de ROAS,
+  o se audite la implementación técnica de conversión tracking.
+version: "1.0.0"
+herramientasPermitidas: [Read]
+evolvable: true  # default para skill estandar
+exclusiones:
+  - "No cargar para tracking de conversiones en el browser o server-side con GTM, GA4, Meta CAPI — para implementación de tracking web cargar `tracking-measurement`."
+  - "No cargar para estrategia de pujas, definición de presupuesto o copy de anuncios — esas son decisiones de negocio y marketing, no técnicas."
+  - "No cargar para integraciones con plataformas distintas a Google Ads (Meta Ads, TikTok Ads, LinkedIn Ads) sin relación con la API de Google — para otras plataformas usar el SDK correspondiente."
+  - "No cargar para dashboards de métricas generales de negocio sin datos de Google Ads — para dashboards de observabilidad de sistemas cargar `monitoring-alertas`."
+---
+# paid-media-tracking — Herramientas técnicas para publicidad pagada
+
+## Cuándo NO cargar
+
+- La tarea es tracking de conversiones en el browser o server-side (GTM, GA4, Meta CAPI): cargar `tracking-measurement`.
+- La tarea es estrategia de pujas, presupuesto o copy de anuncios: son decisiones de negocio, no de ingeniería.
+- La integración es con Meta Ads, TikTok Ads o LinkedIn Ads sin relación con Google Ads API: usar el SDK del proveedor.
+- La tarea es un dashboard de métricas generales de negocio sin datos específicos de Google Ads: cargar `monitoring-alertas`.
+
+## Cuándo cargar este skill
+
+```
+✅ Construir reportes automáticos de Google Ads (Python, Node)
+✅ Implementar un sistema de alertas sobre rendimiento de campañas
+✅ Integrar Google Ads API con un CRM o backend
+✅ Diseñar el schema de dataLayer para campañas de e-commerce
+✅ Construir un dashboard de ROAS con datos de la API
+✅ Automatizar la gestión de negative keywords programáticamente
+✅ Implementar auditoría técnica de cuentas Google Ads
+❌ Definir estrategia de pujas (es trabajo del PPC strategist, no del ingeniero)
+❌ Crear copys de anuncios (creativo, no técnico)
+❌ Tomar decisiones de presupuesto (decisión de negocio)
+```
+
+> Para tracking de conversiones browser/server-side (GTM, GA4, Meta CAPI),
+> cargar `Skill("tracking-measurement")` en su lugar o en paralelo.
+
+## Conceptos clave
+
+- **ROAS** (Return on Ad Spend): `valor_conversiones / costo`. Métrica primaria de rentabilidad de campañas.
+- **Micros**: Google Ads almacena costos en micros (millonésimas). `cost_micros / 1_000_000` = valor real.
+- **GAQL**: Google Ads Query Language. SQL-like para consultar la API. Recursos, segmentos y métricas tienen nombres específicos.
+- **MCC** (Manager Customer Center): cuenta paraguas que agrupa sub-cuentas. El `login_customer_id` debe apuntar al MCC.
+- **Search Term View**: recurso de la API que expone los términos exactos que activaron los anuncios — diferente a las keywords configuradas.
+
+## Reglas obligatorias
+
+### Regla 1 — Siempre dividir `cost_micros` entre 1,000,000
+
+Google Ads devuelve todos los costos en micros. Operar con micros produce
+cifras de ROAS, CPA y presupuesto completamente erróneas.
+
+```python
+# MAL — opera con micros directamente
+roas = conversiones_valor / row.metrics.cost_micros
+
+# BIEN — convierte primero
+costo = row.metrics.cost_micros / 1_000_000
+roas = conversiones_valor / costo if costo > 0 else 0
+```
+
+**Verificación**: El costo de una campaña típica en MXN debe estar en
+el rango de decenas a miles, nunca en millones.
+
+### Regla 2 — Manejar `GoogleAdsException` siempre
+
+La API devuelve errores granulares por campo y operación. Un `except Exception`
+silencia información crítica (quota excedida, permiso denegado, ID inválido).
+
+```python
+from google.ads.googleads.errors import GoogleAdsException
+
+try:
+    response = ga_service.search(customer_id=customer_id, query=query)
+except GoogleAdsException as ex:
+    for error in ex.failure.errors:
+        logger.error(
+            "Error Google Ads [%s]: %s",
+            error.error_code,
+            error.message,
+        )
+    raise
+```
+
+**Verificación**: Los logs deben mostrar `error_code` y `message` específicos,
+no solo el texto genérico de la excepción.
+
+### Regla 3 — `customer_id` sin guiones
+
+La Google Ads API rechaza el formato `123-456-7890`. El formato correcto es
+la cadena de dígitos sin guiones: `"1234567890"`.
+
+```python
+# MAL
+customer_id = "123-456-7890"
+
+# BIEN
+customer_id = "1234567890"
+# O limpiar al recibir del usuario:
+customer_id = customer_id.replace("-", "")
+```
+
+**Verificación**: Un `INVALID_CUSTOMER_ID` en los logs indica este problema.
+
+### Regla 4 — Nunca hardcodear credenciales de la API
+
+`developer_token`, `refresh_token` y `client_secret` son credenciales de
+producción. Van en variables de entorno o en un gestor de secretos.
+
+```python
+# MAL
+client = GoogleAdsClient.load_from_dict({
+    "developer_token": "ABcDeFgHiJkLmNoPq",
+    "refresh_token": "1//0gXyz...",
+})
+
+# BIEN
+client = GoogleAdsClient.load_from_dict({
+    "developer_token": settings.GOOGLE_ADS_DEVELOPER_TOKEN,
+    "client_id": settings.GOOGLE_ADS_CLIENT_ID,
+    "client_secret": settings.GOOGLE_ADS_CLIENT_SECRET,
+    "refresh_token": settings.GOOGLE_ADS_REFRESH_TOKEN,
+    "login_customer_id": settings.GOOGLE_ADS_MCC_ID,
+})
+```
+
+### Regla 5 — Cachear respuestas de la API al menos 1 hora
+
+La API tiene quota diaria limitada (1,000 operaciones/día en nivel básico).
+Llamar la API en cada request HTTP agota la quota en minutos con tráfico real.
+
+```python
+from functools import lru_cache
+import time
+
+_cache: dict = {}
+_TTL = 3600  # 1 hora
+
+def obtener_con_cache(clave: str, fn_obtener):
+    """Caché simple con TTL para respuestas de Google Ads API."""
+    ahora = time.time()
+    if clave in _cache and (ahora - _cache[clave]["ts"]) < _TTL:
+        return _cache[clave]["data"]
+    datos = fn_obtener()
+    _cache[clave] = {"data": datos, "ts": ahora}
+    return datos
+```
+
+## Google Ads API — cliente Python
+
+```python
+from google.ads.googleads.client import GoogleAdsClient
+from google.ads.googleads.errors import GoogleAdsException
+
+client = GoogleAdsClient.load_from_dict({
+    "developer_token": settings.GOOGLE_ADS_DEVELOPER_TOKEN,
+    "client_id": settings.GOOGLE_ADS_CLIENT_ID,
+    "client_secret": settings.GOOGLE_ADS_CLIENT_SECRET,
+    "refresh_token": settings.GOOGLE_ADS_REFRESH_TOKEN,
+    "login_customer_id": settings.GOOGLE_ADS_MCC_ID,
+})
+
+def obtener_rendimiento_campanas(customer_id: str, dias: int = 30) -> list[dict]:
+    """Obtiene métricas de rendimiento de campañas de los últimos N días."""
+    ga_service = client.get_service("GoogleAdsService")
+
+    query = f"""
+        SELECT
+            campaign.id,
+            campaign.name,
+            campaign.status,
+            metrics.impressions,
+            metrics.clicks,
+            metrics.conversions,
+            metrics.cost_micros,
+            metrics.conversions_value
+        FROM campaign
+        WHERE segments.date DURING LAST_{dias}_DAYS
+            AND campaign.status = 'ENABLED'
+        ORDER BY metrics.cost_micros DESC
+    """
+
+    try:
+        response = ga_service.search(customer_id=customer_id, query=query)
+        resultados = []
+        for row in response:
+            costo = row.metrics.cost_micros / 1_000_000
+            roas = (row.metrics.conversions_value / costo) if costo > 0 else 0
+
+            resultados.append({
+                "id": str(row.campaign.id),
+                "nombre": row.campaign.name,
+                "impresiones": row.metrics.impressions,
+                "clicks": row.metrics.clicks,
+                "conversiones": row.metrics.conversions,
+                "costo": round(costo, 2),
+                "roas": round(roas, 2),
+            })
+        return resultados
+
+    except GoogleAdsException as ex:
+        for error in ex.failure.errors:
+            raise ValueError(f"Error Google Ads: {error.message}") from ex
+```
+
+## Análisis de search terms para detección de desperdicio
+
+Consultar la implementación completa de `analizar_search_terms` en
+[recursos/auditoria-tracking.md](recursos/auditoria-tracking.md).
+
+Patrón de detección de desperdicio: si `costo > 50` y `conversiones == 0`,
+el término es candidato a negative keyword. Analizar bigramas y trigramas
+(n=2 y n=3) sobre el vocabulario de search terms para encontrar patrones
+de términos irrelevantes frecuentes.
+
+## Detección de discrepancias entre plataformas
+
+Consultar la función `ejecutar_auditoria_completa` en
+[recursos/auditoria-tracking.md](recursos/auditoria-tracking.md).
+
+Umbral aceptable: discrepancia < 15% entre Google Ads y GA4.
+Causas frecuentes: ventanas de conversión distintas, modelos de atribución
+diferentes (last-click vs data-driven), o conversiones offline no importadas.
+
+## Anti-patrones críticos
+
+| Anti-patrón | Problema | Solución |
+|-------------|----------|----------|
+| Operar con `cost_micros` sin convertir | ROAS y CPA erróneos por factor 1,000,000 | Dividir siempre entre `1_000_000` |
+| `customer_id` con guiones `123-456-7890` | `INVALID_CUSTOMER_ID` de la API | `customer_id.replace("-", "")` |
+| Llamar la API en cada request HTTP | Quota agotada en minutos | Caché con TTL de 1 hora mínimo |
+| Credenciales en código fuente | Exposición en repositorio | Variables de entorno obligatorias |
+| Filtrar sin considerar `campaign.status` | `PAUSED`/`REMOVED` contaminan reportes activos | Filtro explícito por status en GAQL |
+| Usar `login_customer_id` de sub-cuenta en MCC | Accede a cuenta incorrecta o da error de permisos | Siempre el ID del MCC para cuentas administradas |
+
+## Checklist de verificación
+
+- [ ] `cost_micros` se divide entre `1_000_000` antes de cualquier operación aritmética
+- [ ] `GoogleAdsException` capturada con iteración sobre `ex.failure.errors`
+- [ ] `customer_id` sin guiones antes de llamar a la API
+- [ ] Credenciales en variables de entorno (`settings.*`), no hardcodeadas
+- [ ] Respuestas de la API con caché de al menos 1 hora
+- [ ] Filtro de `campaign.status` en todas las queries de campañas activas
+- [ ] `search_stream` usado para queries que puedan devolver >10,000 filas
+
+## Referencias a recursos
+
+| Tema | Archivo |
+|------|---------|
+| Google Ads API: autenticación, quota, GAQL avanzado, batch operations | [recursos/google-ads-api.md](recursos/google-ads-api.md) |
+| Auditoría técnica: checklist de cuenta, métricas de calidad, reporte Python | [recursos/auditoria-tracking.md](recursos/auditoria-tracking.md) |
+
+## Gotchas / Errores comunes no obvios
+
+**La GAQL query con `WHERE segments.date DURING LAST_30_DAYS` incluye el día actual con datos parciales, inflando el conteo de conversiones del período**: si se corre el reporte a las 10 AM, el día de hoy tiene solo 10 horas de datos pero se incluye en el agregado de 30 días como si fuera un día completo. Para comparativas de períodos (mes actual vs mes anterior), esto produce distorsión. Causa: `LAST_N_DAYS` incluye el día actual con datos hasta el momento de la query. Fix: usar `BETWEEN YYYY-MM-DD AND YYYY-MM-DD` con fechas explícitas excluyendo el día actual, calculadas en Python: `fecha_fin = datetime.today() - timedelta(days=1)`.
+
+**El `login_customer_id` correcto para MCC es el ID de la cuenta administradora, pero las queries retornan datos de TODAS las sub-cuentas mezclados si no se especifica `customer_id` por sub-cuenta**: si el MCC administra 50 cuentas y se hace una query de campañas sin filtrar por `customer_id`, la API devuelve campañas de todas las sub-cuentas con los mismos nombres, haciendo imposible distinguir a qué cuenta pertenece cada fila. Causa: el `login_customer_id` habilita el acceso al MCC pero `customer_id` en `search()` determina el scope. Fix: iterar sobre los sub-`customer_id` obtenidos de `CustomerService` y hacer una query por cuenta, o usar el campo `customer.id` en el `SELECT` de GAQL para incluir el ID de cuenta en cada fila del resultado.
+
+**`search_stream` no puede usarse con queries que incluyen `ORDER BY` porque la API de streaming no garantiza orden y lanza `STREAMING_NOT_SUPPORTED_FOR_SORTED_QUERIES`**: al migrar de `search()` a `search_stream()` para manejar resultados grandes, las queries con `ORDER BY metrics.cost_micros DESC` fallan con un error poco descriptivo. Causa: el streaming de Google Ads API envía filas en el orden de procesamiento interno del servidor, no en el orden especificado. Fix: usar `search()` con paginación para queries ordenadas, y `search_stream()` solo para queries sin `ORDER BY`. Si se necesita orden + volumen grande, hacer el sort en Python después de recibir todos los resultados.
+
+**Las conversiones de Google Ads tienen una ventana de atribución de 30-90 días, por lo que los datos de ROAS de los últimos 7 días siguen cambiando durante semanas después**: un reporte ejecutado el lunes puede mostrar ROAS de 2.1 para la semana anterior, pero el mismo período consultado 3 semanas después puede mostrar ROAS de 2.8 porque se atribuyeron conversiones tardías. Causa: la API devuelve los datos con las conversiones atribuidas hasta el momento de la query, no las del período. Fix: para reportes comparativos históricos, documentar la fecha de extracción y no comparar el período "de esta semana" contra períodos anteriores sin usar datos ya consolidados (más de 90 días atrás). Para dashboards en tiempo real, aceptar que los últimos 90 días tienen datos en evolución y mostrar la fecha de actualización.