@saulwade/swl-ses 1.0.0

package/habilidades/backend-mcp-servidor/SKILL.md

@@ -0,0 +1,270 @@
+---
+name: backend-mcp-servidor
+description: >
+  Diseño de servidores MCP (Model Context Protocol) para exponer capacidades
+  a Claude y otros clientes compatibles. Cubre los cinco patrones de producción
+  de Anthropic: servidores remotos first, agrupación de tools por intención,
+  code orchestration en sandbox para APIs grandes, elicitation mid-tool-call,
+  y autenticación con CIMD + Vaults. Cargar cuando se diseñe o revise un
+  servidor MCP, cuando se integre una API externa a agentes vía MCP en lugar
+  de tool use directo, o cuando un servicio deba ser alcanzable desde Claude,
+  ChatGPT, Cursor o VS Code sin rehacer la integración por cliente.
+version: "1.0.0"
+herramientasPermitidas: [Read, Write, Edit, Bash]
+exclusiones:
+  - "No cargar para diseñar el consumo de un servidor MCP existente — eso es tool use estándar, no diseño de servidor; este skill cubre SOLO el lado del servidor."
+  - "No cargar para integraciones locales vía CLI (stdio transport) con ~10 tools — el overhead de diseñar un servidor MCP solo vale para casos con alcance multi-cliente o >50 tools."
+  - "No cargar para reemplazar un API REST existente — un servidor MCP complementa APIs, no las sustituye; diseña primero la API REST y luego decide si exponerla vía MCP."
+  - "No cargar para flujos de auth simples (API key estática) — MCP se beneficia de OAuth+CIMD; si el caso admite API key fija, un endpoint REST es más simple que un servidor MCP completo."
+evolvable: true
+---
+
+# backend-mcp-servidor — Diseño de servidores MCP para producción
+
+Diseñas servidores MCP que puedan alcanzar múltiples clientes (Claude, ChatGPT,
+Cursor, VS Code) sin rehacer la integración para cada uno. El enfoque viene del
+artículo de Anthropic sobre agentes en producción con MCP (2026-04) y de las
+convenciones del MCP SDK oficial.
+
+## Cuándo cargar
+
+- Al diseñar un servidor MCP nuevo que expondrá una API interna a agentes.
+- Al revisar un servidor MCP existente buscando reducir tokens en contexto.
+- Al evaluar si un caso amerita MCP vs tool use directo con la API de Anthropic.
+- Al integrar una API externa grande (>50 endpoints) como Cloudflare, GitHub,
+  Notion con agentes.
+- Al decidir la estrategia de autenticación de un servidor MCP multi-tenant.
+
+## Cuándo NO cargar
+
+- Integraciones con pocas tools (≤10) y un solo cliente (Claude Code local) —
+  stdio transport con tool use directo es más simple.
+- Reemplazo de una API REST existente — MCP complementa, no sustituye.
+- Flujos de autenticación con API key estática sin OAuth — un endpoint HTTP
+  básico es más ligero.
+- Diseño del lado del consumidor — este skill es para el servidor; el consumo
+  usa tool use estándar.
+
+## Reglas obligatorias
+
+1. **Remote-first si hay más de un cliente objetivo** — porque un servidor
+   local con stdio transport solo alcanza un cliente; remoto (SSE o HTTP) con
+   TLS alcanza cualquier cliente compatible con MCP y se despliega una sola vez.
+2. **Agrupar tools por intención, no por endpoints** — porque un agente razona
+   mejor con una tool de alto nivel (`create_issue_from_thread`) que con tres
+   primitivos encadenados (`get_thread` → `parse_messages` → `create_issue`);
+   menos pasos implican menos alucinaciones y menos tokens.
+3. **Code orchestration para APIs con más de 50 endpoints** — porque listar
+   500+ tools en contexto costaría miles de tokens y el modelo se pierde entre
+   alternativas; 2 tools (`search` + `execute`) ejecutando scripts en sandbox
+   son la solución probada (referencia: Cloudflare MCP server con ~2,500
+   endpoints reducidos a ~1K tokens).
+4. **Elicitation solo para acciones destructivas o de pago** — porque pausar
+   la ejecución para pedir confirmación quiebra el flujo del agente; usarlo
+   únicamente cuando la reversibilidad o el costo justifican la fricción.
+5. **Autenticación OAuth con CIMD; NUNCA embeber credenciales en tool_input** —
+   porque los parámetros de una tool se registran en logs, se muestran al
+   usuario y quedan en el historial del agente; los tokens OAuth deben vivir
+   en el servidor vía Vaults o gestor de secretos, no en el protocolo MCP.
+
+## Patrón 1 — Remote-first vs local
+
+Un servidor MCP local (stdio) solo lo ejecuta un cliente a la vez. Un servidor
+remoto (SSE/HTTP con TLS) atiende a todos los clientes de todos los usuarios.
+
+| Transporte | Cuándo |
+|---|---|
+| `stdio` | Desarrollo local, integraciones con CLI tools, ≤10 tools, un cliente |
+| `SSE` (Server-Sent Events) | Producción single-tenant con streaming bidireccional |
+| `HTTP streamable` | Producción multi-tenant con autenticación OAuth |
+
+**Heurística:** si el servicio tiene clientes humanos y agentes, diseñar
+directamente HTTP streamable. Nunca "empezar local y migrar después" — el
+costo de reescribir auth y state management supera el beneficio.
+
+## Patrón 2 — Tool grouping por intención
+
+MAL (expone endpoints):
+
+```python
+@mcp.tool()
+def get_thread(thread_id: str) -> dict: ...
+
+@mcp.tool()
+def parse_messages(thread: dict) -> list: ...
+
+@mcp.tool()
+def create_issue(title: str, body: str, labels: list[str]) -> str: ...
+```
+
+BIEN (expone intenciones):
+
+```python
+@mcp.tool()
+def create_issue_from_thread(
+    thread_id: str,
+    extra_labels: list[str] | None = None,
+) -> IssueCreated:
+    """Crea un issue a partir de un hilo de Slack/Discord/email.
+
+    Extrae automáticamente el título, el cuerpo y las etiquetas
+    relevantes del hilo, crea el issue en el tracker configurado
+    y retorna su URL.
+    """
+```
+
+Criterio: si un agente invocaría las 3 tools primitivas siempre en el mismo
+orden y con los mismos parámetros derivados, eso es UNA intención. Exponer solo
+la intención reduce tokens y decisiones del modelo.
+
+## Patrón 3 — Code orchestration para APIs grandes
+
+Cuando la API tiene >50 endpoints, exponer dos tools que permitan al agente
+descubrir y ejecutar dinámicamente:
+
+```python
+@mcp.tool()
+def search(query: str, limit: int = 10) -> list[ToolDescriptor]:
+    """Busca endpoints disponibles por descripción."""
+
+@mcp.tool()
+def execute(script: str, inputs: dict) -> ExecutionResult:
+    """Ejecuta un script Python que compone llamadas a la API
+    real en un sandbox aislado. El script recibe un cliente
+    pre-autenticado como variable `api` y retorna JSON."""
+```
+
+Ejecución en sandbox (obligatorio — porque código arbitrario del agente
+sin aislamiento es inyección confirmada): `subprocess` con `timeout`,
+`resource` limits de CPU/memoria, sin acceso a filesystem del host,
+red filtrada al dominio del API destino únicamente.
+
+Cloudflare usa este patrón con sus ~2,500 endpoints, reduciendo la huella
+en contexto a ~1K tokens vs >50K con tools individuales.
+
+## Patrón 4 — Elicitation mid-tool-call
+
+Permite pausar la ejecución de una tool para pedir input estructurado al
+usuario (formulario) o mostrar una URL (flujo OAuth, pago):
+
+```python
+@mcp.tool()
+async def transfer_funds(
+    from_account: str,
+    to_account: str,
+    amount: Decimal,
+) -> TransferResult:
+    # Pausa: pide confirmación antes de ejecutar
+    confirmation = await ctx.elicit(
+        mode="form",
+        schema={
+            "type": "object",
+            "properties": {
+                "confirm": {"type": "boolean", "title": "¿Confirmas la transferencia?"},
+            },
+            "required": ["confirm"],
+        },
+    )
+    if not confirmation["confirm"]:
+        return TransferResult(status="cancelled_by_user")
+    # Ejecuta solo si el usuario confirmó
+    return await _ejecutar_transferencia(from_account, to_account, amount)
+```
+
+Modos: `form` (JSON Schema → UI de formulario), `url` (abrir navegador para
+OAuth o pago), `text` (texto libre).
+
+Criterio de uso: solo para operaciones irreversibles o con costo económico.
+Pausar cada tool rompe la autonomía del agente y frustra al usuario.
+
+## Patrón 5 — Autenticación OAuth con CIMD + Vaults
+
+CIMD (Client ID Metadata Documents) estandariza el OAuth entre clientes MCP
+sin que cada uno registre su app por separado.
+
+Flujo recomendado:
+
+1. El cliente MCP descubre el servidor → obtiene el manifiesto con
+   `authorization_servers`.
+2. Redirige al usuario al authorization server con CIMD del cliente.
+3. El token emitido se guarda en el Vault del servidor MCP (no en el cliente,
+   no en los parámetros de tools).
+4. Cada tool_call del cliente incluye un session_id; el servidor resuelve
+   las credenciales desde el Vault usando ese session_id.
+
+Never hacer:
+
+- Embeber `api_key` en los parámetros de una tool — queda en logs y
+  en el historial del agente.
+- Devolver tokens en el response de una tool — el modelo puede filtrarlos en
+  su razonamiento visible.
+- Usar una API key compartida para múltiples usuarios — rompe auditoría
+  y el principio de menor privilegio.
+
+## Estructura mínima del servidor
+
+```
+mi-mcp-servidor/
+├── pyproject.toml          # mcp>=1.0.0, fastmcp, httpx
+├── src/
+│   ├── server.py           # entry point con FastMCP
+│   ├── tools/              # una tool de intención por archivo
+│   ├── auth/               # manejo de CIMD + Vault
+│   ├── sandbox/            # execute() si usa code orchestration
+│   └── resources/          # MCP resources (si aplica)
+├── tests/
+│   ├── test_tools_integration.py   # contra un cliente MCP real
+│   └── test_auth_flow.py
+└── README.md
+```
+
+Dependencias mínimas: `mcp` (SDK oficial Python) o `@modelcontextprotocol/sdk`
+(TypeScript). Evitar abstracciones propietarias sobre MCP — el estándar
+evoluciona y los wrappers se rompen.
+
+## Gotchas
+
+- **Tool search defiere carga, no la elimina** — los tools siguen existiendo;
+  el modelo los pide por descripción cuando los necesita. Si el conteo es
+  absurdo (>1,000), rediseñar con code orchestration; tool search sola no
+  arregla un catálogo mal agrupado.
+- **Elicitation no suspende el timeout del agente** — si el usuario tarda 5
+  minutos en confirmar, el agente sigue consumiendo el reloj del cliente.
+  Configurar timeouts explícitos en el servidor para reiniciar el diálogo si
+  el usuario abandona.
+- **Programmatic tool calling requiere que la API destino sea idempotente** —
+  si el script del sandbox falla a la mitad, el re-run duplica efectos. Para
+  operaciones no idempotentes, combinar con elicitation.
+- **Vaults no son gratis en latencia** — resolver el secreto por session_id
+  agrega ~5-20ms por tool_call. Cachear con TTL corto (60s) dentro del
+  servidor, nunca en el cliente.
+- **SSE vs HTTP streamable** — SSE es más simple pero no soporta request
+  body grande; para inputs de tool_call con payload >1MB (documentos,
+  imágenes), usar HTTP streamable.
+- **Cualquier herramienta que toma credenciales como parámetro es una vulnerabilidad** —
+  porque quedan en logs de request, en transcripts del agente y en historial
+  del cliente. Siempre resolver credenciales por identidad del usuario, nunca
+  aceptarlas como input.
+- **MCP Apps con interfaces ricas requieren capability negotiation** — no todo
+  cliente soporta renderizado de formularios o gráficos. El servidor debe
+  degradar a respuesta texto plano cuando `capabilities.ui` está ausente.
+
+## Integración con SWL
+
+- **`reglas/seguridad-agentes.md`** — sección "Gobernanza de MCP" define
+  cómo evaluar un servidor MCP antes de conectarlo desde SWL; este skill cubre
+  el lado servidor correspondiente.
+- **`/swl:mcp-status`** — valida salud de servidores MCP conectados; útil
+  cuando desarrolles tu propio servidor para probar descubrimiento.
+- **`backend-api-swl`** — agente que diseña APIs; invocar antes de este skill
+  si la API base aún no existe.
+- **`arquitecto-swl`** — si la decisión "MCP vs REST vs GraphQL" aún no está
+  tomada, producir un ADR antes de cargar este skill.
+
+## Referencias
+
+- Artículo Anthropic 2026-04: "Building agents that reach production systems with MCP".
+- MCP SDK oficial Python: https://github.com/modelcontextprotocol/python-sdk
+- MCP SDK oficial TypeScript: https://github.com/modelcontextprotocol/typescript-sdk
+- Directorio público de servidores MCP: https://github.com/modelcontextprotocol/servers
+- Cloudflare MCP server (referencia de code orchestration).

package/habilidades/backend-production-resilience/SKILL.md

@@ -0,0 +1,288 @@
+---
+name: backend-production-resilience
+description: >
+  Patrones de resiliencia para servicios backend en producción. Cubre timeouts
+  obligatorios, retries con jitter+backoff e idempotency, circuit breakers,
+  bulkheads, backpressure, graceful degradation, blast radius, fault isolation
+  y observabilidad operacional. Cargar cuando se diseñe o revise un servicio
+  que llame a dependencias externas (BD, APIs, colas, caches), cuando se
+  diagnostique un incidente de producción, o cuando se quiera endurecer
+  endpoints contra sobrecarga, latencia y fallas en cascada.
+version: "1.0.0"
+evolved: false
+herramientasPermitidas: [Read]
+exclusiones:
+  - "No cargar para resiliencia de agentes IA o cadenas de delegación — cargar `seguridad-agentes` o `guardrail-semantico`. Este skill cubre servicios web/API/backend, no orquestación de agentes."
+  - "No cargar para definición de SLO/SLI o error budgets — cargar `sre-patrones`. Este skill cubre patrones de implementación; SRE cubre el framework de confiabilidad."
+  - "No cargar para configuración de monitoreo (Prometheus, Grafana, alertas) — cargar `monitoring-alertas`. Este skill cubre qué emitir desde el código; monitoreo cubre cómo capturarlo y graficarlo."
+  - "No cargar para manejo de errores genérico (jerarquía de excepciones, códigos de dominio) — cargar `manejo-errores`. Este skill asume que ese ya está aplicado y agrega patrones de resiliencia operacional encima."
+evolvable: true
+---
+
+# Backend Production Resilience
+
+## Cuándo cargar
+
+- Se diseña o revisa un servicio que llama dependencias externas (BD, APIs HTTP, colas, caches, filesystem remoto).
+- Se diagnostica un incidente de producción: latencia, timeouts en cascada, OOM, retry storms.
+- Se prepara un endpoint público para tráfico real (no solo el happy path).
+- Se va a integrar un nuevo cliente HTTP o driver de BD: aplicar timeouts y circuit breaker desde el inicio.
+- Se hace code review de un PR que toca integración con sistemas externos.
+
+## Cuándo NO cargar
+
+- La tarea es definir SLO/SLI o calcular error budgets — usar `sre-patrones`.
+- La tarea es configurar dashboards o alertas en Prometheus/Grafana — usar `monitoring-alertas`.
+- El problema es resiliencia de cadenas de agentes IA o blast radius de delegación — usar `seguridad-agentes`.
+- El servicio aún no maneja errores correctamente — primero cargar `manejo-errores` y aplicar la jerarquía base; este skill asume manejo de errores ya correcto.
+
+## Directiva primaria
+
+**La producción es desordenada por defecto.** Toda dependencia externa puede ser
+lenta, no estar disponible o devolver datos incorrectos. Toda cola se llena.
+Todo cache puede fallar o sufrir stampede. Todo timeout puede cascadear.
+
+Diseñar para que el servicio:
+
+1. **Falle visible** en lugar de colgarse en silencio.
+2. **Limite el blast radius** en lugar de propagar la falla.
+3. **Descarte carga** en lugar de colapsar bajo presión.
+4. **Preserve servicios core** cuando hay degradación.
+5. **Permita diagnóstico** desde los logs, métricas y trazas.
+
+No diseñar solo para el happy path.
+
+## Mindset de estabilidad — 6 axiomas
+
+1. Toda dependencia puede ser lenta, no responder o estar mal.
+2. Toda cola se puede llenar.
+3. Todo cache puede fallar o sufrir stampede.
+4. Todo timeout puede cascadear hacia arriba.
+5. Todo caller puede reintentar mal (DDoSearte sin querer).
+6. Todo estado "temporal degradado" puede convertirse en normal por horas.
+
+El código debe asumir estas condiciones por construcción, no tolerarlas por accidente.
+
+---
+
+## Timeouts — obligatorios, no opcionales
+
+- Toda llamada de salida (HTTP, DB query, cache get, cola publish) DEBE tener
+  un timeout explícito.
+- El timeout va en el código, NO se hereda del default de la librería.
+  Los defaults suelen ser infinitos o demasiado largos.
+- Distintas dependencias pueden tener distintos presupuestos de timeout
+  según su SLA conocido. No usar un único valor global.
+- Esperas infinitas están prohibidas. Sin excepción.
+
+```python
+# MAL — sin timeout, defaults dependen de la librería
+async with httpx.AsyncClient() as client:
+    r = await client.get(url)  # puede colgar indefinidamente
+
+# BIEN — timeout explícito por nivel (connect, read, write, pool)
+TIMEOUT = httpx.Timeout(connect=2.0, read=5.0, write=2.0, pool=1.0)
+async with httpx.AsyncClient(timeout=TIMEOUT) as client:
+    r = await client.get(url)
+```
+
+Para BD: el timeout va en el statement (`statement_timeout` en PostgreSQL,
+`maxTimeMS` en MongoDB), no solo en el connection pool.
+
+---
+
+## Retries — disciplinados o ninguno
+
+- Reintenta solo operaciones **idempotentes** (GET, PUT, DELETE) o
+  explícitamente diseñadas con idempotency key (POST con header
+  `Idempotency-Key: <uuid>`).
+- Acotar el conteo de reintentos Y el tiempo total de reintentos.
+- Aplicar **jitter** y **backoff exponencial** para evitar tormentas de
+  reintentos sincronizados.
+- NUNCA reintentes errores 4xx (client error). Reintenta solo 408, 429,
+  5xx (excepto 501, 505) y errores de red transitorios.
+- Si el caller también reintenta, los reintentos se multiplican
+  exponencialmente — preferir un solo nivel de retry en la cadena.
+
+```python
+import random
+async def retry_con_jitter(fn, intentos=3, base_delay=0.5, max_delay=8.0):
+    """Backoff exponencial completo + jitter aleatorio (AWS Architecture Blog)."""
+    for intento in range(intentos):
+        try:
+            return await fn()
+        except (httpx.TimeoutException, httpx.NetworkError) as e:
+            if intento == intentos - 1:
+                raise
+            cap = min(max_delay, base_delay * (2 ** intento))
+            await asyncio.sleep(random.uniform(0, cap))  # full jitter
+```
+
+---
+
+## Circuit breakers
+
+Cuando una dependencia está fallando, **dejar de llamarla** durante un
+período corto en lugar de seguir intentando y consumir threads/conexiones.
+
+Estados:
+- **CLOSED**: peticiones pasan normalmente.
+- **OPEN**: peticiones fallan inmediatamente (no se llama a la dependencia).
+- **HALF_OPEN**: tras un timeout, se permiten N peticiones de prueba; si
+  pasan, vuelve a CLOSED; si fallan, vuelve a OPEN.
+
+Reglas:
+- Definir thresholds explícitos: tasa de error (ej: ≥50% de las últimas
+  20 llamadas) y tiempo de cooldown (ej: 30s).
+- El circuit breaker DEBE emitir métricas con el cambio de estado para
+  que se monitoree.
+- En estado OPEN, devolver una respuesta degradada (cache, default, error
+  visible al caller) — nunca colgar.
+- Probar el comportamiento del CB con tests específicos: simular dependencia
+  caída y verificar que el CB abre, sostiene y vuelve a HALF_OPEN.
+
+Librerías recomendadas: `pybreaker` (Python), `opossum` (Node.js),
+`resilience4j` (Java).
+
+---
+
+## Bulkheads — aislamiento de fallos
+
+Aislar pools de recursos por dependencia para que una dependencia lenta
+no agote todos los threads/conexiones del servicio:
+
+- Pools separados de conexiones HTTP por upstream crítico.
+- Pools separados de threads/workers por tipo de tarea.
+- Tamaño máximo del pool acotado: si hay tráfico que excede capacidad,
+  fallar rápido en lugar de hacer cola infinita.
+
+```python
+# Cliente HTTP con pool dedicado por upstream (httpx)
+cliente_pagos = httpx.AsyncClient(
+    timeout=TIMEOUT_PAGOS,
+    limits=httpx.Limits(max_connections=20, max_keepalive_connections=10),
+)
+cliente_inventario = httpx.AsyncClient(
+    timeout=TIMEOUT_INVENTARIO,
+    limits=httpx.Limits(max_connections=50, max_keepalive_connections=20),
+)
+```
+
+Sin bulkheads, una dependencia lenta puede consumir todos los workers y
+dejar al servicio sin capacidad para responder otros endpoints.
+
+---
+
+## Backpressure y descarte de carga
+
+Cuando el servicio recibe más peticiones de las que puede procesar, debe
+DESCARTAR carga rápidamente en lugar de hacer cola y degradar a todos.
+
+Patrones:
+- **Rate limiting** por cliente/endpoint (token bucket, sliding window).
+  Devolver `429 Too Many Requests` con header `Retry-After`.
+- **Cola acotada**: si la cola interna excede N items, rechazar nuevas
+  con `503 Service Unavailable`.
+- **Load shedding**: bajo CPU/memoria altos, rechazar peticiones no-críticas
+  primero, preservar servicios core.
+- **Admission control**: rechazar peticiones que probablemente excederán
+  el deadline antes de empezar a procesarlas.
+
+NO usar colas en memoria ilimitadas — un upstream lento las llena hasta
+provocar OOM.
+
+---
+
+## Graceful degradation
+
+Cuando una dependencia no-crítica falla, el servicio debe seguir
+funcionando con funcionalidad reducida en lugar de devolver error
+completo:
+
+- Catalogar dependencias en críticas vs. mejoradoras (recommendations,
+  analytics, notifications son típicamente mejoradoras).
+- Si una dependencia mejoradora falla: registrar la falla, devolver
+  resultado degradado (sin recommendations, sin notification enviada
+  pero encolada para retry).
+- El cliente debe poder distinguir entre respuesta completa y
+  respuesta degradada (ej: header `X-Service-Degraded: notifications`).
+
+Antipatrón: si el servicio de notifications falla, fallar la operación
+de checkout completa. Eso convierte una dependencia mejoradora en
+crítica.
+
+---
+
+## Blast radius — contención del impacto
+
+Diseñar para que una falla aislada NO se propague a todo el sistema:
+
+- Particionar usuarios/tenants en shards independientes (un shard caído
+  no tira a otros tenants).
+- Separar workloads críticos de no-críticos en infraestructura distinta
+  (un job de reportes pesado no debe usar el mismo pool que el checkout).
+- Limitar el alcance de cambios deployable: feature flags por usuario o
+  porcentaje, canary deployments, blue-green.
+
+Pregunta de revisión: si esta dependencia se cae a las 3am del sábado,
+**¿cuántos usuarios se ven afectados y por cuánto tiempo?**
+
+---
+
+## Observabilidad obligatoria
+
+Sin observabilidad, los patrones anteriores son invisibles cuando fallan.
+Mínimo requerido:
+
+- **Métricas RED por endpoint**: Rate (req/s), Errors (count/rate), Duration
+  (p50/p95/p99).
+- **Estado de circuit breakers**: gauge por dependencia (0=closed, 1=open).
+- **Saturación de pools**: utilización de connection pool, queue depth.
+- **Latencia por dependencia externa**: histograma separado por upstream.
+- **Logs estructurados** con correlation ID que cruce el request completo.
+- **Trazas distribuidas** (OpenTelemetry) para diagnosticar latencia
+  cross-service.
+
+Si un patrón de resiliencia se activa (CB abre, retry consume budget,
+load shedding descarta) DEBE quedar registrado con suficiente contexto
+para diagnóstico post-mortem.
+
+---
+
+## Anti-patrones
+
+- **Retry sin jitter**: causa retry storm sincronizado que tira la
+  dependencia justo cuando se está recuperando.
+- **Timeout en el caller pero no en el callee**: el callee sigue
+  procesando una petición ya abandonada — desperdicia recursos.
+- **Catch-all `except Exception` con log y continue**: oculta fallas
+  reales, hace el servicio "imposible de diagnosticar".
+- **Cola en memoria sin límite**: tarde o temprano OOM.
+- **Reintentar 4xx**: errores del cliente no se arreglan reintentando.
+- **Misma dependencia compartiendo pool con todas las demás**: cuando
+  esa dependencia lenta llega, mata todo el servicio.
+- **CB sin métricas**: nadie se entera cuando abre, falla en silencio.
+
+---
+
+## Gotchas / Errores comunes no obvios
+
+- **`asyncio.wait_for` no cancela la operación interna en algunas librerías**: el timeout dispara pero la operación sigue corriendo en background consumiendo recursos. Causa: la librería interna no propaga `CancelledError`. Solución: verificar que la librería soporta cancelación cooperativa; si no, ejecutar en thread separado con `loop.run_in_executor` y matarlo explícitamente.
+- **Reintento sobre POST sin idempotency key duplica órdenes**: si la red corta antes de recibir la respuesta, el caller no sabe si se procesó. Causa: POST por defecto no es idempotente. Solución: requerir `Idempotency-Key: <uuid>` en POST que muten estado, persistir el key con la respuesta, devolver la misma respuesta si llega una repetición.
+- **Circuit breaker con threshold absoluto en lugar de tasa**: el CB nunca abre porque "10 errores" tarda en alcanzarse en bajo tráfico, pero abre falsamente con "10 errores en 1000 req". Causa: threshold absoluto sin ventana temporal. Solución: usar tasa de error sobre ventana deslizante (ej: 50% de errores en últimas 20 peticiones o últimos 10s).
+- **Backoff exponencial sin cap**: tras varios fallos, el delay crece a 30 minutos y el caller percibe como cuelgue. Causa: olvidar `max_delay`. Solución: siempre acotar con `min(cap, base * 2**n)` (capped exponential backoff).
+- **Bulkhead omitido entre tenants**: un tenant grande consume todo el pool y deja a los demás esperando. Causa: pool global, no por tenant. Solución: pool por tenant o tenant pesos en admission control.
+
+## Checklist antes de poner un servicio en producción
+
+- [ ] Toda llamada externa tiene timeout explícito (no default).
+- [ ] Retries acotados, con jitter+backoff, solo en operaciones idempotentes.
+- [ ] Circuit breaker configurado para cada dependencia externa crítica.
+- [ ] Pools separados por dependencia (bulkheads).
+- [ ] Rate limiting en endpoints públicos.
+- [ ] Cola interna con límite (rechazar 503 al exceder).
+- [ ] Catálogo de dependencias críticas vs. mejoradoras documentado.
+- [ ] Métricas RED + estado CB + saturación pools instrumentadas.
+- [ ] Logs estructurados con correlation ID.
+- [ ] Trazas distribuidas configuradas (OpenTelemetry).
+- [ ] Test de chaos: simular latencia/caída de cada dependencia y verificar comportamiento.