@saulwade/swl-ses 1.0.0

package/habilidades/paid-media-tracking/recursos/auditoria-tracking.md

@@ -0,0 +1,220 @@
+# Auditoría técnica de cuentas Google Ads
+
+## Checklist técnico de auditoría
+
+Una auditoría técnica verifica que la infraestructura de medición está
+correctamente configurada — no evalúa la estrategia de campañas.
+
+### Conversiones
+
+- [ ] **Conversiones primarias configuradas**: al menos una acción de conversión
+  marcada como "Primaria" en la cuenta. Las conversiones secundarias no se usan
+  en las estrategias de puja automática.
+- [ ] **Enhanced Conversions activadas**: en Configuración de conversiones,
+  "Enhanced conversions for web" debe estar habilitado con hash SHA-256.
+- [ ] **Auto-tagging habilitado**: en Configuración de la cuenta, permite que
+  Google Ads agregue `gclid` a las URLs de destino para importación a GA4.
+- [ ] **Sin conversiones duplicadas**: verificar que el mismo evento de compra
+  no esté configurado dos veces (una en GA4-importada y otra en etiqueta directa).
+- [ ] **Ventana de conversión correcta**: campañas de búsqueda usan 30 días;
+  campañas de display o video pueden requerir ventanas más largas (90 días).
+
+### Audiencias y remarketing
+
+- [ ] **Etiqueta de remarketing activa**: Google Ads Tag o GA4 Audience deben
+  estar recibiendo datos (verificar en Audience Manager > Fuentes de audiencia).
+- [ ] **Audiencias de remarketing creadas**: al menos "Todos los visitantes",
+  "Visitantes de producto" y "Compradores anteriores" para campañas RLSA.
+- [ ] **Customer Match habilitado**: si se usa lista de clientes, la cuenta debe
+  tener historial suficiente y cumplimiento de políticas.
+
+### Shopping (si aplica)
+
+- [ ] **Feed de productos aprobado** en Merchant Center: sin errores de
+  disponibilidad, precio o imagen. Los items rechazados no aparecen en anuncios.
+- [ ] **Vinculación Merchant Center — Google Ads**: confirmada en ambas cuentas.
+- [ ] **Etiquetas personalizadas configuradas**: para segmentación por margen,
+  temporada o prioridad de inventario.
+
+### Estructura técnica de la cuenta
+
+- [ ] **Naming convention consistente**: campañas, ad groups y keywords siguen
+  una nomenclatura que permite filtrar y reportar programáticamente.
+- [ ] **UTM parameters en URLs finales**: `utm_source=google&utm_medium=cpc&utm_campaign={campaignid}`
+  para atribución correcta en GA4 sin depender solo del auto-tagging.
+
+---
+
+## Métricas de calidad de cuenta
+
+Estas métricas indican la salud técnica de la implementación, no el
+desempeño de negocio:
+
+| Métrica | Objetivo | Señal de problema |
+|---------|----------|------------------|
+| Quality Score promedio (búsqueda) | ≥ 7/10 | < 5 indica relevancia baja o landing page deficiente |
+| Impression Share de marca | ≥ 85% | < 70% indica competencia capturando tráfico de marca |
+| Invalid click rate | < 2% | > 5% indica fraude de clics o tráfico de baja calidad |
+| Discrepancia GA4 vs Google Ads | < 15% | > 15% indica problema de tracking o atribución |
+| Conversiones con valor cero | 0% | Cualquier conversión primaria sin valor = ROAS incalculable |
+
+### Query para Quality Score promedio
+
+```python
+def obtener_quality_score_promedio(customer_id: str) -> dict:
+    """Obtiene Quality Score promedio de keywords activas."""
+    ga_service = client.get_service("GoogleAdsService")
+
+    query = """
+        SELECT
+            ad_group_criterion.keyword.text,
+            ad_group_criterion.quality_info.quality_score,
+            ad_group_criterion.quality_info.creative_quality_score,
+            ad_group_criterion.quality_info.post_click_quality_score,
+            ad_group_criterion.quality_info.search_predicted_ctr,
+            metrics.impressions
+        FROM keyword_view
+        WHERE campaign.status = 'ENABLED'
+            AND ad_group.status = 'ENABLED'
+            AND ad_group_criterion.status = 'ENABLED'
+            AND ad_group_criterion.quality_info.quality_score > 0
+            AND segments.date DURING LAST_30_DAYS
+    """
+
+    response = ga_service.search(customer_id=customer_id, query=query)
+
+    scores = []
+    impresiones_total = 0
+    suma_ponderada = 0
+
+    for row in response:
+        qs = row.ad_group_criterion.quality_info.quality_score
+        imp = row.metrics.impressions
+        scores.append(qs)
+        suma_ponderada += qs * imp
+        impresiones_total += imp
+
+    if not scores:
+        return {"error": "sin_keywords_con_quality_score"}
+
+    return {
+        "promedio_simple": round(sum(scores) / len(scores), 1),
+        "promedio_ponderado_impresiones": round(
+            suma_ponderada / impresiones_total, 1
+        ) if impresiones_total > 0 else 0,
+        "total_keywords": len(scores),
+        "distribucion": {
+            "excelente_8_10": sum(1 for s in scores if s >= 8),
+            "bueno_6_7": sum(1 for s in scores if 6 <= s <= 7),
+            "bajo_1_5": sum(1 for s in scores if s <= 5),
+        },
+    }
+```
+
+---
+
+## Herramientas de diagnóstico
+
+### Google Tag Assistant
+
+Extensión de Chrome para verificar que la etiqueta de Google Ads está
+disparando correctamente en el sitio:
+
+1. Activar grabación en la página objetivo
+2. Completar el flujo de conversión (compra, registro, etc.)
+3. Verificar que el evento aparece en el historial con los parámetros correctos
+4. Confirmar que no hay errores de "Tag not found" o "Tag fired multiple times"
+
+### Google Ads Diagnostics Tool
+
+En la consola de Google Ads: Herramientas > Diagnóstico y vista previa
+de anuncios. Permite verificar por qué un anuncio no aparece para una
+búsqueda específica (presupuesto agotado, keyword pausada, policy violation).
+
+---
+
+## Reporte automático de auditoría con Python
+
+```python
+import json
+from dataclasses import dataclass, field
+
+@dataclass
+class ResultadoAuditoria:
+    customer_id: str
+    quality_score: dict = field(default_factory=dict)
+    discrepancia_conversiones: dict = field(default_factory=dict)
+    candidatos_negative: list = field(default_factory=list)
+    alertas: list[str] = field(default_factory=list)
+
+def ejecutar_auditoria_completa(
+    customer_id: str,
+    ga4_conversiones: float,
+    campaign_ids: list[str],
+) -> ResultadoAuditoria:
+    """
+    Ejecuta auditoría técnica completa de una cuenta Google Ads.
+
+    Retorna un ResultadoAuditoria con métricas de calidad,
+    discrepancias de conversiones y candidatos a negative keywords.
+    """
+    resultado = ResultadoAuditoria(customer_id=customer_id)
+
+    # 1. Quality Score
+    resultado.quality_score = obtener_quality_score_promedio(customer_id)
+    qs_prom = resultado.quality_score.get("promedio_simple", 0)
+    if qs_prom < 7:
+        resultado.alertas.append(
+            f"Quality Score promedio bajo: {qs_prom}/10 (objetivo ≥ 7)"
+        )
+
+    # 2. Rendimiento de campañas y discrepancia de conversiones
+    campanas = obtener_rendimiento_campanas(customer_id)
+    google_ads_conv = sum(c["conversiones"] for c in campanas)
+    resultado.discrepancia_conversiones = detectar_discrepancia_conversiones(
+        google_ads_conv, ga4_conversiones
+    )  # Nota: esta función es async en SKILL.md, adaptar según contexto
+
+    if resultado.discrepancia_conversiones.get("estado") != "ok":
+        pct = resultado.discrepancia_conversiones.get("discrepancia_porcentual", 0)
+        resultado.alertas.append(
+            f"Discrepancia de conversiones: {pct}% (umbral: 15%)"
+        )
+
+    # 3. Search terms con desperdicio
+    analisis = analizar_search_terms(customer_id, campaign_ids)
+    resultado.candidatos_negative = analisis["candidatos_negative"][:10]
+    if resultado.candidatos_negative:
+        total_desperdicio = sum(
+            t["costo_desperdiciado"] for t in resultado.candidatos_negative
+        )
+        resultado.alertas.append(
+            f"{len(resultado.candidatos_negative)} términos candidatos a negative, "
+            f"costo desperdiciado estimado: ${total_desperdicio:,.2f}"
+        )
+
+    return resultado
+
+
+def exportar_reporte_json(resultado: ResultadoAuditoria, ruta: str) -> None:
+    """Exporta el resultado de la auditoría como JSON."""
+    import dataclasses
+    with open(ruta, "w", encoding="utf-8") as f:
+        json.dump(dataclasses.asdict(resultado), f, ensure_ascii=False, indent=2)
+```
+
+### Ejemplo de uso
+
+```python
+resultado = ejecutar_auditoria_completa(
+    customer_id="1234567890",
+    ga4_conversiones=142.0,
+    campaign_ids=["111222333", "444555666"],
+)
+
+print(f"Alertas encontradas: {len(resultado.alertas)}")
+for alerta in resultado.alertas:
+    print(f"  - {alerta}")
+
+exportar_reporte_json(resultado, "auditoria_2026_04.json")
+```

package/habilidades/paid-media-tracking/recursos/google-ads-api.md

@@ -0,0 +1,215 @@
+# Google Ads API — Referencia técnica
+
+## Autenticación
+
+### Tipos de credenciales
+
+| Tipo | Cuándo usar | Configuración requerida |
+|------|-------------|------------------------|
+| OAuth2 con refresh token | Acceso en nombre de un usuario | `client_id`, `client_secret`, `refresh_token` |
+| Service Account | Procesos server-side sin interacción humana | Archivo JSON de service account + acceso delegado en MCC |
+| Developer Token | Obligatorio en todos los casos | Aprobado por Google en la cuenta MCC principal |
+
+### Niveles del Developer Token
+
+| Nivel | Quota diaria | Cuentas accesibles |
+|-------|-------------|-------------------|
+| Test | 15,000 ops/día | Solo cuentas de prueba |
+| Basic | 1,000 ops/día | Todas las cuentas vinculadas al MCC |
+| Standard | 10,000 ops/día | Requiere solicitud y aprobación de Google |
+
+En producción con reportes diarios, **Standard es necesario** si se tienen
+más de 50 cuentas o consultas de más de 30 días de datos.
+
+### Configuración con diccionario Python
+
+```python
+from google.ads.googleads.client import GoogleAdsClient
+
+config = {
+    "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,  # ID del MCC, sin guiones
+    "use_proto_plus": True,  # Objetos Python nativos en lugar de protobuf raw
+}
+
+client = GoogleAdsClient.load_from_dict(config)
+```
+
+### Configuración con archivo YAML (alternativa)
+
+```yaml
+# google-ads.yaml (NO subir a repositorio)
+developer_token: "Tu_Developer_Token"
+client_id: "client_id.apps.googleusercontent.com"
+client_secret: "client_secret"
+refresh_token: "1//0g..."
+login_customer_id: "1234567890"
+use_proto_plus: true
+```
+
+```python
+client = GoogleAdsClient.load_from_storage("google-ads.yaml")
+```
+
+---
+
+## GAQL — Google Ads Query Language
+
+### Estructura básica
+
+```sql
+SELECT campo1, campo2, metrica1
+FROM recurso_principal
+WHERE condicion1 AND condicion2
+ORDER BY metrica1 DESC
+LIMIT 100
+```
+
+### Recursos principales
+
+| Recurso | Qué contiene |
+|---------|-------------|
+| `campaign` | Campañas: nombre, status, tipo, presupuesto |
+| `ad_group` | Grupos de anuncios dentro de campañas |
+| `ad_group_ad` | Anuncios individuales con sus métricas |
+| `keyword_view` | Keywords configuradas con Quality Score |
+| `search_term_view` | Términos exactos que activaron anuncios |
+| `geographic_view` | Rendimiento por ubicación geográfica |
+| `audience_view` | Rendimiento por audiencia configurada |
+| `shopping_performance_view` | Rendimiento de campañas Shopping |
+
+### Segmentos comunes
+
+Los segmentos dividen las métricas por dimensión. No todos son compatibles
+con todos los recursos — la API retorna error si se combina incorrectamente.
+
+```sql
+-- Segmentar por fecha
+SELECT campaign.name, metrics.clicks, segments.date
+FROM campaign
+WHERE segments.date DURING LAST_30_DAYS
+
+-- Segmentar por dispositivo
+SELECT campaign.name, metrics.clicks, segments.device
+FROM campaign
+WHERE segments.date DURING LAST_7_DAYS
+
+-- Rangos de fecha explícitos
+WHERE segments.date BETWEEN '2026-01-01' AND '2026-03-31'
+```
+
+### Períodos predefinidos útiles
+
+| Constante GAQL | Equivalente |
+|----------------|-------------|
+| `LAST_7_DAYS` | Últimos 7 días |
+| `LAST_30_DAYS` | Últimos 30 días |
+| `LAST_MONTH` | Mes calendario anterior completo |
+| `THIS_MONTH` | Mes calendario actual hasta hoy |
+| `LAST_YEAR` | Año anterior completo |
+
+### Filtros de status importantes
+
+```sql
+-- Solo campañas activas (ENABLED)
+WHERE campaign.status = 'ENABLED'
+
+-- Campañas activas y pausadas (excluye eliminadas)
+WHERE campaign.status IN ('ENABLED', 'PAUSED')
+
+-- Search terms de campañas activas únicamente
+WHERE campaign.status = 'ENABLED'
+    AND ad_group.status = 'ENABLED'
+```
+
+---
+
+## Paginación y streaming
+
+### `search` vs `search_stream`
+
+| Método | Cuándo usar | Comportamiento |
+|--------|-------------|----------------|
+| `search` | Resultados esperados < 10,000 filas | Devuelve páginas de 10,000 resultados |
+| `search_stream` | Resultados esperados > 10,000 filas | Stream de chunks, más eficiente en memoria |
+
+```python
+# Para datasets grandes (search terms de cuentas con alto volumen)
+stream = ga_service.search_stream(customer_id=customer_id, query=query)
+resultados = []
+for batch in stream:
+    for row in batch.results:
+        resultados.append(procesar_fila(row))
+```
+
+---
+
+## Batch operations con `MutateGoogleAdsRequest`
+
+Para operaciones de escritura (agregar negative keywords, pausar campañas),
+agrupar en un solo request reduce el consumo de quota.
+
+```python
+from google.ads.googleads.client import GoogleAdsClient
+
+def agregar_negative_keywords(
+    customer_id: str,
+    campaign_id: str,
+    terminos: list[str],
+) -> None:
+    """Agrega lista de negative keywords a una campaña en un solo request."""
+    campaign_criterion_service = client.get_service("CampaignCriterionService")
+
+    operaciones = []
+    for termino in terminos:
+        operacion = client.get_type("CampaignCriterionOperation")
+        criterio = operacion.create
+        criterio.campaign = f"customers/{customer_id}/campaigns/{campaign_id}"
+        criterio.negative = True
+        criterio.keyword.text = termino
+        criterio.keyword.match_type = client.enums.KeywordMatchTypeEnum.BROAD
+        operaciones.append(operacion)
+
+    campaign_criterion_service.mutate_campaign_criteria(
+        customer_id=customer_id,
+        operations=operaciones,
+    )
+```
+
+---
+
+## Errores comunes y solución
+
+| Error | Causa probable | Solución |
+|-------|----------------|----------|
+| `PERMISSION_DENIED` | `login_customer_id` incorrecto o sin acceso | Verificar que el MCC tiene acceso a la sub-cuenta |
+| `QUOTA_ERROR` | Quota diaria agotada | Implementar caché, solicitar nivel Standard |
+| `NOT_FOUND` | `customer_id` o `campaign_id` no existe | Verificar IDs sin guiones |
+| `INVALID_CUSTOMER_ID` | `customer_id` con guiones | `customer_id.replace("-", "")` |
+| `AUTHENTICATION_ERROR` | `refresh_token` vencido o revocado | Regenerar refresh token en Google OAuth Playground |
+| `RESOURCE_EXHAUSTED` | Demasiados requests en poco tiempo | Implementar retry con backoff exponencial |
+
+### Retry con backoff exponencial
+
+```python
+import time
+from google.ads.googleads.errors import GoogleAdsException
+
+def ejecutar_con_retry(fn, max_reintentos: int = 3):
+    """Ejecuta una llamada a la API con retry y backoff exponencial."""
+    for intento in range(max_reintentos):
+        try:
+            return fn()
+        except GoogleAdsException as ex:
+            es_quota = any(
+                "QUOTA" in str(e.error_code) for e in ex.failure.errors
+            )
+            if es_quota and intento < max_reintentos - 1:
+                espera = 2 ** intento  # 1s, 2s, 4s
+                time.sleep(espera)
+                continue
+            raise
+```

package/habilidades/patrones-python/SKILL.md

@@ -0,0 +1,228 @@
+---
+name: patrones-python
+description: Idiomas pythonicos, PEP 8, type hints modernos, dataclasses, async/await, context managers, decorators y generators. Patrones de código limpio en Python.
+version: "1.3.0"
+evolved: true
+evolved-from: "1.2.0"
+evolved-at: "2026-04-27"
+evolved-by: "aprender"
+evolved-note: "3 secciones nuevas (regex multi-pattern al extender scope, tracer/replicador con marca SYNC, fixtures crudos vs condensados) + refinamiento de la sección caché content-addressable (sharding, bypass env var, key multi-dimensión, tests obligatorios). Preserva F401 en soft imports. Patrones avanzados extraídos a recursos/patrones-avanzados.md para respetar el límite de 300 líneas de SKILL.md."
+herramientasPermitidas: [Read, Glob, Grep]
+exclusiones:
+  - "No cargar para patrones de un framework específico (FastAPI, Django, Celery) — los idiomas generales de este skill aplican, pero los patrones de framework tienen restricciones adicionales; cargar el skill del framework correspondiente."
+  - "No cargar para errores de instalación o dependencias Python — si el problema es pip, virtualenv o incompatibilidad de versiones, cargar `build-errors-python`."
+  - "No cargar para patrones de concurrencia avanzados (TaskGroup, semáforos, event loops) — para esos cargar `async-python` que cubre asyncio en profundidad."
+  - "No cargar para testing pytest (fixtures, mocking, cobertura) — ese dominio está en `testing-python` que cubre la toolchain completa de tests."
+evolvable: true  # default para skill estandar
+---
+# Patrones Python
+
+## Cuándo NO cargar
+
+- La tarea es específica de FastAPI o Django — cargar el skill del framework que tiene restricciones adicionales a los patrones generales.
+- El problema es de instalación de dependencias Python — cargar `build-errors-python`.
+- La pregunta es sobre concurrencia avanzada con asyncio — cargar `async-python`.
+
+## PEP 8 — Convenciones de estilo
+
+### Nomenclatura
+
+```python
+# Módulos y paquetes: snake_case minúsculas
+import mi_modulo
+
+# Clases: PascalCase
+class FacturaElectronica:
+    pass
+
+# Funciones y variables: snake_case
+def calcular_iva(monto: float) -> float:
+    tasa_iva = 0.16
+    return monto * tasa_iva
+
+# Constantes: UPPER_SNAKE_CASE
+MAX_REINTENTOS = 3
+URL_BASE_API = "https://api.ejemplo.com/v1"
+
+# Variables privadas de instancia: prefijo _
+class Factura:
+    def __init__(self):
+        self._numero_interno = None  # privado por convención
+```
+
+### Longitud de línea y formato
+
+```python
+# Máximo 88 caracteres (configuración Black estándar)
+
+# Importaciones agrupadas:
+# 1. Stdlib
+import os
+from pathlib import Path
+
+# 2. Terceros
+from fastapi import FastAPI, Depends
+from sqlalchemy.orm import Session
+
+# 3. Módulos locales
+from app.models.usuario import Usuario
+```
+
+---
+
+## Type Hints modernos (Python 3.10+)
+
+```python
+# Union con | en vez de Union[X, Y]
+def procesar(valor: int | str | None) -> str:
+    return str(valor or "")
+
+# list, dict, tuple nativos (no de typing)
+def filtrar(items: list[str], lookup: dict[str, int]) -> list[str]:
+    return [i for i in items if i in lookup]
+
+# TypeAlias explícito
+type JSON = dict[str, "JSON"] | list["JSON"] | str | int | float | bool | None
+
+# ParamSpec para decoradores que preservan firma
+from typing import ParamSpec, Callable
+P = ParamSpec("P")
+
+def con_log(fn: Callable[P, T]) -> Callable[P, T]:
+    def wrapper(*args: P.args, **kwargs: P.kwargs) -> T:
+        print(f"Llamando {fn.__name__}")
+        return fn(*args, **kwargs)
+    return wrapper
+```
+
+---
+
+## Dataclasses
+
+```python
+from dataclasses import dataclass, field
+from datetime import datetime
+
+@dataclass
+class Producto:
+    id: str
+    nombre: str
+    precio: float
+    activo: bool = True
+    etiquetas: list[str] = field(default_factory=list)
+
+    def __post_init__(self) -> None:
+        if self.precio < 0:
+            raise ValueError(f"Precio no puede ser negativo: {self.precio}")
+        self.nombre = self.nombre.strip()
+
+# Dataclass inmutable
+@dataclass(frozen=True)
+class Coordenada:
+    latitud: float
+    longitud: float
+
+# Dataclass con slots (Python 3.10+) — ahorra memoria
+@dataclass(slots=True)
+class EventoAuditoria:
+    usuario_id: str
+    accion: str
+    timestamp: datetime
+```
+
+---
+
+## Context Managers
+
+```python
+from contextlib import contextmanager, asynccontextmanager
+
+# Context manager con generador
+@contextmanager
+def medir_tiempo(nombre: str):
+    inicio = time.perf_counter()
+    try:
+        yield
+    finally:
+        transcurrido = time.perf_counter() - inicio
+        print(f"{nombre}: {transcurrido:.4f}s")
+
+# Context manager async
+@asynccontextmanager
+async def sesion_db(engine):
+    async with engine.begin() as conn:
+        try:
+            yield conn
+            await conn.commit()
+        except Exception:
+            await conn.rollback()
+            raise
+```
+
+---
+
+## Anti-patrones Python Críticos
+
+```python
+# MAL: argumento mutable como default
+def agregar(item, lista=[]):   # La lista persiste entre llamadas
+    lista.append(item)
+
+# BIEN: usar None como centinela
+def agregar(item, lista=None):
+    if lista is None:
+        lista = []
+    lista.append(item)
+
+# MAL: bare except
+try:
+    operacion_riesgosa()
+except:
+    pass  # silencia KeyboardInterrupt y SystemExit
+
+# BIEN: excepción específica
+try:
+    operacion_riesgosa()
+except ValueError as e:
+    logger.error(f"Valor inválido: {e}")
+
+# MAL: concatenación en loop (O(n²))
+resultado = ""
+for parte in partes:
+    resultado += parte
+
+# BIEN: join (O(n))
+resultado = "".join(partes)
+```
+
+Para generators, decoradores avanzados, async/await y manejo de errores idiomático,
+ver [recursos/referencia-completa.md](recursos/referencia-completa.md).
+
+## Gotchas / Errores comunes no obvios
+
+- **`dataclass` con campo mutable como default (`field: list = []`) produce un objeto compartido entre todas las instancias**: Python reutiliza el objeto por defecto en vez de crear uno nuevo. Causa: los defaults de dataclass se evalúan en tiempo de definición de la clase, no en cada instanciación — una lista mutable como default es el mismo objeto en memoria para todas las instancias. Solución: usar `field(default_factory=list)` para campos mutables: `from dataclasses import field; tags: list = field(default_factory=list)`.
+- **Decorator que usa `functools.wraps` pero no preserva type hints si la función decorada tiene anotaciones genéricas**: el `@wraps` copia `__wrapped__`, `__doc__` y `__name__`, pero el tipo de retorno inferido por `mypy` es el del wrapper, no el del wrapped. Causa: `functools.wraps` no puede preservar el tipado estático del wrapped — mypy ve el tipo del wrapper `Callable[..., Any]`. Solución: usar `TypeVar` y tipado genérico en el decorator con `ParamSpec` (Python 3.10+): `P = ParamSpec('P'); T = TypeVar('T')` y tipar el wrapper como `Callable[P, T]`.
+- **`__slots__` en clase Python produce `TypeError: multiple bases have instance lay-out conflict`** al heredar de otra clase con `__slots__`: las subclases con `__slots__` requieren que todos los ancestros también tengan `__slots__`, o que el ancestro directo sea `object`. Causa: si `ClaseBase` no tiene `__slots__`, tiene un `__dict__` implícito; si `ClaseHija` tiene `__slots__`, hay conflicto de layout de memoria. Solución: o agregar `__slots__ = ()` vacío a la clase base, o eliminar `__slots__` de la subclase — no mezclar clases con y sin `__slots__` en la misma jerarquía.
+- **`property` setter que modifica un campo privado no refleja el cambio en `__repr__` generado por dataclass**: el `@property` en un dataclass crea un campo de clase que conflictúa con el campo de instancia del dataclass. Causa: `@dataclass` genera `__repr__` basado en los campos declarados en `__init__` — si el setter modifica un atributo con nombre diferente (ej: `_valor`), `__repr__` muestra el campo original sin la modificación. Solución: usar `field(init=False, repr=False)` para el campo interno y exponer solo la `property` en la interfaz pública.
+
+---
+
+## Patrones avanzados (carga bajo demanda)
+
+Los siguientes patrones aparecen al integrar Python con pipelines reales
+(conversores de documentos, clientes heterogéneos, cachés determinísticos,
+detectores de texto, duplicación deliberada de lógica). El detalle completo
+está en [recursos/patrones-avanzados.md](recursos/patrones-avanzados.md).
+
+| # | Patrón | Cargar cuando |
+|---|--------|---------------|
+| 1 | Normalizadores: colapsar al formato canónico del PROYECTO | escribir `_normalizar(texto)` después de un conversor externo (MarkItDown, Pandoc, mammoth) |
+| 2 | kwargs opcionales entre clientes hermanos: try/except TypeError | propagar un kwarg nuevo a clientes con signature heterogénea sin romper la interfaz |
+| 3 | Caché content-addressable por SHA256 | función pura costosa (>1 s) que se invoca repetidamente con los mismos inputs |
+| 4 | F401 en archivos con soft imports es intencional | módulo importa una dependencia opcional dentro de `try/except ImportError` |
+| 5 | Detectores regex multi-pattern: extender scope sin refinar genera FP | un detector con OR de patterns se va a aplicar a un texto más ruidoso que el original |
+| 6 | Tracer/replicador paralelo del motor: marca SYNC obligatoria | duplicar lógica del motor para telemetría, explainability o shadow runs |
+| 7 | Fixtures con datos pre-procesados NO ejercen el path crudo | el motor prefiere leer un campo crudo opcional sobre uno condensado, y los fixtures son condensados |
+
+Cargar la sección específica del recurso cuando aplique al problema en mano —
+no cargar el archivo completo si solo se necesita un patrón.