@saulwade/swl-ses 1.3.8 → 1.4.0

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

@@ -1,288 +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.
+---
+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.