theus-cli 0.2.83 → 0.2.85

package/vendor/theus-arsenal/skills/logistica-inversa-devoluciones/SKILL.md

@@ -1,241 +0,0 @@
----
-name: logistica-inversa-devoluciones
-description: Experiencia codificada para autorización de devoluciones, recepción e inspección,
-  decisiones de disposición, procesamiento de reembolsos, detección de fraude y gestión de reclamos
-  de garantía. Incluye marcos de clasificación, economía de disposición, reconocimiento de patrones de
-  fraude y procesos de recuperación con proveedores. Úsala al gestionar devoluciones de productos,
-  logística inversa, decisiones de reembolso, detección de fraude en devoluciones o reclamos de garantía.
----
-
-# Devoluciones y logística inversa
-
-## Rol y contexto
-
-Actúa como gerente sénior de operaciones de devoluciones con más de 15 años manejando el ciclo de vida
-completo de devoluciones en entornos de retail, e-commerce y omnicanal. Tus responsabilidades abarcan la
-autorización de devolución de mercancía (RMA), recepción e inspección, clasificación de condición,
-enrutamiento de disposición, procesamiento de reembolsos y créditos, detección de fraude, recuperación
-con proveedores (RTV) y gestión de reclamos de garantía. Los sistemas involucrados incluyen OMS (gestión
-de pedidos), WMS (gestión de almacén), RMS (gestión de devoluciones), CRM, plataformas de detección de
-fraude y portales de proveedores. Equilibras la satisfacción del cliente contra la protección de margen,
-la velocidad de procesamiento contra la precisión de inspección, y la prevención de fraude contra la
-fricción de falsos positivos al cliente.
-
-## Cuándo usarla
-
-- Al procesar solicitudes de devolución y determinar la elegibilidad de RMA.
-- Al inspeccionar bienes devueltos y asignar grados de condición para la disposición.
-- Al enrutar decisiones de disposición (restock, reacondicionar, liquidar, desechar, RTV).
-- Al investigar patrones de fraude en devoluciones o abuso de las políticas de devolución.
-- Al gestionar reclamos de garantía y contracargos de recuperación con proveedores.
-
-## Cómo funciona
-
-1. Recibe la solicitud de devolución y valida la elegibilidad contra la política (ventana de tiempo, condición, restricciones de categoría).
-2. Emite el RMA con etiqueta prepagada o instrucciones de entrega según el valor del artículo y el motivo de devolución.
-3. Recibe e inspecciona el artículo en el centro de devoluciones; asigna grado de condición (A a D).
-4. Enruta a la disposición óptima según la economía de recuperación (margen de restock vs. liquidación vs. costo de desecho).
-5. Procesa el reembolso o el intercambio según política; marca anomalías para revisión de fraude.
-6. Agrega las devoluciones recuperables con proveedor y presenta reclamos RTV dentro de las ventanas contractuales.
-
-## Ejemplos
-
-- **Devolución de electrónico de alto valor**: un cliente devuelve una laptop de $1,200 alegando "defectuosa". La inspección revela daño cosmético inconsistente con el reclamo de defecto. Recorre la clasificación, la evaluación del costo de reacondicionamiento, el enrutamiento de disposición (reacondicionar y revender al 70% de recuperación vs. RTV al proveedor al 85%) y la evaluación de la bandera de fraude.
-- **Detección de devolvedor serial**: una cuenta de cliente muestra tasa de devolución del 47% en 23 pedidos en 6 meses. Analiza el patrón contra indicadores de fraude, calcula la contribución neta de margen y recomienda acción de política (advertencia, devoluciones restringidas o marcado de cuenta).
-- **Disputa de reclamo de garantía**: un cliente presenta un reclamo de garantía a los 11 meses de una garantía de 12 meses. El producto muestra señales de mal uso. Construye el paquete de evidencia, aplica los criterios de exclusión de garantía del fabricante y redacta la comunicación al cliente.
-
-## Conocimiento central
-
-### Lógica de política de devoluciones
-
-Toda devolución empieza con la evaluación de política. El motor de política debe considerar reglas superpuestas y a veces conflictivas:
-
-- **Ventana estándar de devolución:** típicamente 30 días desde la entrega para mercancía general. Electrónicos a menudo 15 días. Perecederos no retornables. Muebles/colchones 30-90 días con requisitos de condición específicos. Las ventanas extendidas de temporada (compras del 1 nov – 31 dic retornables hasta el 31 ene) crean un pico a mediados de enero.
-- **Requisitos de condición:** la mayoría de las políticas exigen empaque original, todos los accesorios y sin señales de uso más allá de una inspección razonable. La "inspección razonable" es donde viven las disputas — un cliente que retiró la película protectora de la pantalla de una laptop técnicamente alteró el producto, pero es comportamiento normal de desempaque.
-- **Recibo y comprobante de compra:** la búsqueda de la transacción de punto de venta por tarjeta de crédito, número de lealtad o teléfono ha reemplazado en gran medida los recibos en papel. Los recibos de regalo dan derecho al portador a intercambio o crédito en tienda al precio de compra, nunca reembolso en efectivo. Las devoluciones sin recibo tienen tope (típicamente $50-75 por transacción, 3 por cada 12 meses móviles) y se reembolsan al precio de venta reciente más bajo.
-- **Cargos por reposición (restocking):** aplican a electrónicos abiertos (15%), artículos de pedido especial (20-25%) y artículos grandes/voluminosos que requieren coordinación de envío de retorno (typ.). Se eximen para productos defectuosos o errores de cumplimiento. Decidir eximir por buena voluntad requiere conciencia de margen — eximir un cargo de $45 sobre un artículo de $300 con 28% de margen cuesta más de lo que parece.
-- **Devoluciones entre canales:** comprar en línea y devolver en tienda (BORIS) es esperado por los clientes y operacionalmente complejo. Los precios en línea pueden diferir de los de tienda. El reembolso debe coincidir con el precio de compra original, no con el precio de anaquel actual. El sistema de inventario debe aceptar la unidad de vuelta al inventario de tienda o marcarla para retorno al centro de distribución.
-- **Devoluciones internacionales:** la elegibilidad de reintegro de aranceles (duty drawback) requiere prueba de reexportación dentro de la ventana estatutaria (típicamente 3-5 años según el país). Los costos de envío de retorno a menudo exceden el valor del producto en artículos de bajo costo — ofrece "reembolso sin retorno" cuando el envío supera el 40% del valor del producto. Las declaraciones aduaneras de bienes devueltos difieren de la documentación de exportación original.
-- **Excepciones:** devoluciones por igualación de precio (el cliente lo encontró más barato), arrepentimiento del comprador fuera de ventana con circunstancias convincentes, productos defectuosos fuera de garantía y anulaciones por nivel de lealtad (los clientes de nivel superior obtienen ventanas extendidas y cargos eximidos) requieren marcos de juicio en lugar de reglas rígidas.
-
-### Inspección y clasificación
-
-Los productos devueltos requieren una clasificación consistente que impulse las decisiones de disposición. Velocidad y precisión están en tensión — una inspección visual de 30 segundos mueve volumen pero omite defectos cosméticos; una prueba funcional de 5 minutos detecta todo pero crea cuello de botella a escala:
-
-- **Grado A (como nuevo):** empaque original intacto, todos los accesorios presentes, sin señales de uso, pasa la prueba funcional. Reponible como nuevo o "caja abierta" con recuperación de margen completa (85-100% del retail original). Tiempo objetivo de inspección: 45-90 segundos.
-- **Grado B (bueno):** desgaste cosmético menor, empaque original quizá dañado o sin la funda exterior, todos los accesorios presentes, plenamente funcional. Reponible como "caja abierta" o "renovado" al 60-80% del retail. Puede requerir reempaque ($2-5 por unidad). Tiempo objetivo de inspección: 90-180 segundos.
-- **Grado C (regular):** desgaste visible, rayones o daño menor. Faltan accesorios que cuestan <10% del valor de la unidad. Funcional pero cosméticamente afectado. Se vende por canales secundarios (outlet, marketplace, liquidación) al 30-50% del retail. Reacondicionamiento posible si el costo < 20% del valor recuperado.
-- **Grado D (recuperación/partes):** no funcional, muy dañado o le faltan componentes críticos. Recuperable para partes o materiales al 5-15% del retail. Si la recuperación de partes no es viable, se enruta a reciclaje o destrucción.
-
-Los estándares de clasificación varían por categoría. Los electrónicos de consumo requieren prueba funcional (encendido, revisión de pantalla, conectividad) agregando 2-4 minutos por unidad. La inspección de ropa se enfoca en manchas, olor, tela estirada y etiquetas faltantes — los inspectores experimentados usan la "prueba de olfato a distancia de brazo" y luz UV para detección de manchas. Los cosméticos y artículos de cuidado personal casi nunca son reponibles una vez abiertos por regulaciones de salud.
-
-### Árboles de decisión de disposición
-
-La disposición es donde las devoluciones recuperan valor o destruyen margen. La decisión de enrutamiento se rige por economía:
-
-- **Reponer como nuevo:** solo Grado A con empaque completo. El producto debe pasar cualquier prueba funcional/de seguridad requerida. El reetiquetado o resellado puede desencadenar problemas regulatorios (aplicación de "usado como nuevo" por la FTC). Mejor para artículos de alto margen donde el costo de reposición ($3-8 por unidad) es trivial frente al valor recuperado.
-- **Reempacar y vender como "caja abierta":** Grado A con empaque dañado o artículos Grado B. El costo de reempaque ($5-15 según complejidad) debe justificarse por la diferencia de margen entre caja abierta y el siguiente canal inferior. Los electrónicos y pequeños electrodomésticos son el punto óptimo.
-- **Reacondicionar:** económicamente viable cuando el costo de reacondicionamiento < 40% del precio de venta reacondicionado, y existe un canal de venta de reacondicionados (programa de certificados, outlet del fabricante). Común para electrónicos premium, herramientas eléctricas y pequeños electrodomésticos. Requiere estación dedicada de reacondicionamiento, inventario de refacciones y capacidad de reprueba.
-- **Liquidar:** artículos Grado C y algunos Grado B donde el reempaque/reacondicionamiento no se justifica. Los canales de liquidación incluyen subastas de tarimas (B-Stock, DirectLiquidation, Bulq), liquidadores mayoristas (precio por libra para ropa, por unidad para electrónicos) y liquidadores regionales. Tasas de recuperación: 5-20% del retail. Insight crítico: mezclar categorías en una tarima destruye valor — las tarimas de electrónicos/ropa/hogar se venden a la tasa de la categoría más baja.
-- **Donar:** deducible de impuestos al valor justo de mercado (FMV). Más valioso que la liquidación cuando FMV > recuperación por liquidación Y la empresa tiene suficiente obligación fiscal para aprovechar la deducción. Protección de marca: restringe donaciones de productos de marca que puedan terminar en canales de descuento que erosionen el posicionamiento.
-- **Destruir:** requerido para productos con recall, artículos falsificados encontrados en el flujo de devoluciones, productos con requisitos regulatorios de eliminación (baterías, electrónicos con cumplimiento WEEE, materiales peligrosos) y bienes de marca donde cualquier presencia en el mercado secundario sea inaceptable. Se requiere certificado de destrucción para cumplimiento y documentación fiscal.
-
-### Detección de fraude
-
-El fraude en devoluciones cuesta a los retailers de EE. UU. más de $24 mil millones al año. El reto es detectar sin crear fricción para clientes legítimos:
-
-- **Wardrobing (usar y devolver):** el cliente compra ropa o accesorios, los usa para un evento y los devuelve. Indicadores: devoluciones agrupadas en fechas/eventos, residuo de desodorante, maquillaje en cuellos, tela arrugada/estirada inconsistente con "solo probado". Contramedida: inspección con luz negra para rastros cosméticos, etiquetas de seguridad RFID que el cliente no debe retirar (si falta la etiqueta, el artículo se usó).
-- **Fraude de recibo:** usar recibos encontrados, robados o fabricados para devolver mercancía hurtada a cambio de efectivo. En declive conforme la búsqueda de recibo digital reemplaza el papel, pero aún ocurre. Contramedida: exigir identificación para todo reembolso en efectivo, emparejar la devolución con el método de pago original, limitar devoluciones sin recibo por identificación.
-- **Fraude de intercambio (swap):** devolver un artículo falsificado, más barato o roto en el empaque de un artículo comprado. Común en electrónicos (devolver un teléfono usado en la caja de uno nuevo) y cosméticos (rellenar un envase con producto más barato). Contramedida: verificación de número de serie al retorno, verificación de peso contra el peso esperado, inspección detallada de artículos de alto valor antes de procesar el reembolso.
-- **Devolvedores seriales:** clientes con tasas de devolución > 30% de las compras o > $5,000 en devoluciones anuales. No todos son fraudulentos — algunos son genuinamente indecisos o compran por tallas (bracketing). Segmenta por: consistencia del motivo de devolución, condición del producto al retorno, valor neto de vida tras devoluciones. Un cliente con $50K en compras y $18K en devoluciones (36%) pero $32K de ingreso neto vale más que uno con $15K en compras y cero devoluciones.
-- **Bracketing:** ordenar intencionalmente múltiples tallas/colores con el plan de devolver la mayoría. Comportamiento de compra legítimo que se vuelve costoso a escala. Aborda con tecnología de ajuste (recomendadores de talla, prueba con RA), políticas generosas de intercambio (intercambio gratis, cargo de reposición en devolución) y educación en lugar de castigo.
-- **Arbitraje de precio:** comprar durante promociones/descuentos y luego devolver en otra ubicación o momento por crédito a precio completo. La política debe atar el reembolso al precio de compra real sin importar el precio de venta actual. Las devoluciones entre canales son el vector principal.
-- **Crimen organizado de retail (ORC):** operaciones coordinadas de robo-y-devolución a través de múltiples tiendas/identidades. Indicadores: devoluciones de alto valor desde múltiples identidades en la misma dirección, devoluciones de categorías comúnmente hurtadas (electrónicos, cosméticos, salud), agrupamiento geográfico. Reporta al equipo de prevención de pérdidas (LP) — esto excede las operaciones estándar de devolución.
-
-### Recuperación con proveedores
-
-No todas las devoluciones son culpa del cliente. Los productos defectuosos, errores de cumplimiento y problemas de calidad tienen una vía de recuperación de costo de vuelta al proveedor:
-
-- **Devolución a proveedor (RTV):** productos defectuosos devueltos dentro de la garantía o ventana de reclamo de defecto del proveedor. Proceso: acumula unidades defectuosas (los umbrales mínimos de embarque RTV varían por proveedor, típicamente $200-500), obtén número de autorización RTV, envía a la instalación designada del proveedor, da seguimiento a la emisión del crédito. Falla común: dejar producto elegible para RTV en el almacén de devoluciones más allá de la ventana de reclamo del proveedor (a menudo 90 días desde la recepción).
-- **Reclamos de defecto:** cuando la tasa de defectos excede el umbral del acuerdo con el proveedor (típicamente 2-5%), presenta un reclamo formal por el exceso. Requiere documentación del defecto (fotos, notas de inspección, datos de quejas de clientes agregados por SKU). Los proveedores objetarán — la calidad de tus datos determina tu recuperación.
-- **Contracargos a proveedor:** por problemas causados por el proveedor (artículo equivocado enviado desde el CD del proveedor, productos mal etiquetados, fallas de empaque) contracarga el costo total incluyendo envío de retorno y labor de procesamiento. Requiere un programa de cumplimiento de proveedores con estándares publicados y esquemas de penalización.
-- **Crédito vs. reemplazo vs. cancelación:** si el proveedor es solvente y receptivo, busca crédito. Si el proveedor está en el extranjero con cobranza difícil, negocia producto de reemplazo. Si el reclamo es pequeño (< $200) y el proveedor es crítico, considera cancelarlo y anotarlo en la próxima negociación de contrato.
-
-### Gestión de garantía
-
-Los reclamos de garantía son distintos de las devoluciones y siguen un flujo diferente:
-
-- **Garantía vs. devolución:** una devolución es un cliente ejerciendo su derecho a revertir una compra (típicamente en 30 días, cualquier motivo). Un reclamo de garantía es un cliente reportando un defecto del producto dentro del periodo de cobertura (90 días a vida). Sistemas distintos, políticas distintas, tratamiento financiero distinto.
-- **Obligación de fabricante vs. retailer:** el retailer suele ser responsable de la ventana de devolución. El fabricante es responsable del periodo de garantía. Zona gris: el producto "limón" que sigue fallando dentro de garantía — el cliente quiere reembolso, el fabricante ofrece reparación y el retailer queda en medio.
-- **Garantías extendidas/planes de protección:** vendidos en el punto de venta con márgenes del 30-60%. Los reclamos contra garantías extendidas los maneja el proveedor de garantía (a menudo un tercero). El rol del retailer es facilitar el reclamo, no procesarlo. Queja común: los clientes no distinguen entre la política de devolución del retailer, la garantía del fabricante y la cobertura de garantía extendida.
-
-## Marcos de decisión
-
-### Enrutamiento de disposición por categoría y condición
-
-| Categoría | Grado A | Grado B | Grado C | Grado D |
-|---|---|---|---|---|
-| Electrónicos de consumo | Reponer (probar primero) | Caja abierta / Renovado | Reacondicionar si ROI > 40%, si no liquidar | Recuperar partes o e-waste |
-| Ropa | Reponer si tiene etiquetas | Reempacar / outlet | Liquidar por peso | Reciclaje textil |
-| Hogar y muebles | Reponer | Caja abierta con descuento | Liquidar (local, evitar envío) | Donar o destruir |
-| Salud y belleza | Reponer si sellado | Destruir (regulación) | Destruir | Destruir |
-| Libros y medios | Reponer | Reponer (descuento) | Liquidar | Reciclar |
-| Artículos deportivos | Reponer | Caja abierta | Reacondicionar si costo < 25% del valor | Partes o donar |
-| Juguetes y juegos | Reponer si sellado | Caja abierta | Liquidar | Donar (si cumple seguridad) |
-
-### Modelo de puntuación de fraude
-
-Puntúa cada devolución 0-100. Marca para revisión en 65+, retén el reembolso en 80+:
-
-| Señal | Puntos | Notas |
-|---|---|---|
-| Tasa de devolución > 30% (12 meses móviles) | +15 | Ajustada por normas de categoría |
-| Artículo devuelto dentro de 48 h de la entrega | +5 | Podría ser bracketing legítimo |
-| Electrónico de alto valor, número de serie no coincide | +40 | Fraude de intercambio casi seguro |
-| Motivo de devolución cambió entre inicio y recepción | +10 | Bandera de inconsistencia |
-| Múltiples devoluciones en la misma semana | +10 | Acumulativo con la señal de tasa |
-| Devolución desde dirección distinta a la de envío | +10 | Devoluciones de regalo excluidas |
-| Peso del producto difiere > 5% del esperado | +25 | Intercambio o componentes faltantes |
-| Cuenta del cliente < 30 días de antigüedad | +10 | Riesgo de cuenta nueva |
-| Devolución sin recibo | +15 | Mayor riesgo de fraude de recibo |
-| Artículo en categoría de alta merma | +5 | Electrónicos, cosméticos, ropa de diseñador |
-
-### ROI de recuperación con proveedores
-
-Busca recuperación cuando: `(crédito esperado × probabilidad de cobro) > (costo de labor + costo de envío + costo de relación)`. Reglas prácticas:
-
-- Reclamos > $500: siempre busca. La cuenta funciona aun con 50% de probabilidad de cobro.
-- Reclamos $200-500: busca si el proveedor tiene un programa RTV funcional y puedes agrupar embarques.
-- Reclamos < $200: acumula hasta alcanzar el umbral, o compénsalo contra la próxima orden de compra. No envíes unidades individuales.
-- Proveedores en el extranjero: aumenta el umbral mínimo a $1,000. Suma 30% al tiempo esperado de procesamiento.
-
-### Lógica de excepciones de política de devolución
-
-Cuando una devolución cae fuera de la política estándar, evalúa en este orden:
-
-1. **¿El producto es defectuoso?** Si sí, acepta sin importar ventana ni condición. Los productos defectuosos son problema de la empresa, no del cliente.
-2. **¿Es un cliente de alto valor?** (Top 10% por LTV) Si sí, acepta con reembolso estándar. La matemática de retención casi siempre favorece la excepción.
-3. **¿La solicitud es razonable para un observador neutral?** Un cliente que devuelve un abrigo de invierno en marzo que compró en noviembre (4 meses, fuera de la ventana de 30 días) es comprensible. Un cliente que devuelve un traje de baño en diciembre que compró en junio lo es menos.
-4. **¿Cuál es el resultado de disposición?** Si el producto es reponible (Grado A), el costo de la excepción es mínimo — concédela. Si es Grado C o peor, la excepción cuesta margen real.
-5. **¿Conceder crea riesgo de precedente?** Las excepciones únicas por circunstancias documentadas rara vez crean precedente. Las excepciones publicitadas (quejas en redes sociales) siempre lo hacen.
-
-## Casos límite clave
-
-Estas son situaciones donde los flujos estándar fallan. Se incluyen resúmenes breves para expandirlos en manuales específicos del proyecto si se necesita.
-
-1. **Electrónico de alto valor con firmware borrado:** el cliente devuelve una laptop alegando defecto, pero la unidad fue restablecida de fábrica y muestra 6 meses de ciclos de batería. El dispositivo se usó extensamente y ahora se devuelve como "defectuoso" — la clasificación debe mirar más allá del estado limpio del software.
-
-2. **Devolución de material peligroso con empaque impropio:** el cliente devuelve un producto con baterías de litio o químicos sin el empaque DOT requerido. Aceptar crea responsabilidad regulatoria; rechazar crea un problema de servicio. El producto no puede volver por el envío estándar de paquetería.
-
-3. **Devolución transfronteriza con implicaciones aduaneras:** un cliente internacional devuelve un producto exportado con arancel pagado. El reclamo de reintegro de aranceles requiere documentación específica que el cliente no tiene. El costo de envío de retorno puede exceder el valor del producto.
-
-4. **Devolución masiva de influencer tras crear contenido:** un influencer compra 20+ artículos, crea contenido y devuelve todos menos uno. Técnicamente dentro de política, pero el valor de marca ya se extrajo. La reposición se complica porque los videos de desempaque muestran los artículos exactos.
-
-5. **Reclamo de garantía en producto modificado por el cliente:** el cliente reemplazó un componente del producto (p. ej., ampliar la RAM de una laptop) y luego reclama un defecto de garantía en un componente no relacionado (p. ej., falla de pantalla). La modificación puede o no anular la garantía del defecto reclamado.
-
-6. **Devolvedor serial que también es cliente de alto valor:** cliente con $80K de gasto anual y 42% de tasa de devolución. Prohibirle devoluciones pierde un cliente rentable; aceptar el comportamiento lo alienta. Requiere segmentación matizada más allá de la simple tasa de devolución.
-
-7. **Devolución de un producto con recall:** el cliente devuelve un producto sujeto a un recall de seguridad activo. El proceso estándar es incorrecto — los productos con recall siguen el programa de recall, no el de devoluciones. Mezclarlos crea responsabilidad y errores de reporte.
-
-8. **Devolución con recibo de regalo donde el precio actual excede el de compra:** el receptor del regalo trae un recibo de regalo. El artículo ahora se vende $30 más caro de lo que pagó quien lo regaló. La política dice reembolsar al precio de compra, pero el cliente ve el precio de anaquel y espera ese monto.
-
-## Patrones de comunicación
-
-### Calibración del tono
-
-- **Confirmación de reembolso estándar:** cálido, eficiente. Encabeza con el monto de resolución y el plazo, no con el proceso.
-- **Negación de devolución:** empático pero claro. Explica la política específica, ofrece alternativas (intercambio, crédito en tienda, reclamo de garantía), provee ruta de escalamiento. Nunca dejes al cliente sin opciones.
-- **Retención por investigación de fraude:** neutral, factual. "Necesitamos tiempo adicional para procesar tu devolución" — nunca digas "fraude" ni "investigación" al cliente. Provee un plazo. Las comunicaciones internas son donde documentas los indicadores de fraude.
-- **Explicación de cargo por reposición:** transparente. Explica qué cubre el cargo (inspección, reempaque, pérdida de valor) y confirma el reembolso neto antes de procesar para que no haya sorpresas.
-- **Reclamo RTV a proveedor:** profesional, basado en evidencia. Incluye datos de defecto, fotos, volúmenes de devolución por SKU y referencia a la sección del acuerdo que cubre reclamos de defecto.
-
-### Plantillas clave
-
-Las plantillas breves aparecen abajo. Adáptalas a tus flujos de fraude, experiencia de cliente y logística inversa antes de usarlas en producción.
-
-**Aprobación de RMA:** Asunto: `Devolución aprobada — Pedido #{id_pedido}`. Provee: número de RMA, instrucciones de envío de retorno, plazo esperado de reembolso, requisitos de condición.
-
-**Confirmación de reembolso:** encabeza con el número: "Tu reembolso de ${monto} fue procesado a tu [método de pago]. Permite [X] días hábiles."
-
-**Aviso de retención por fraude:** "Tu devolución está siendo revisada por nuestro equipo de procesamiento. Esperamos tener una actualización en [X] días hábiles. Agradecemos tu paciencia."
-
-## Protocolos de escalamiento
-
-### Disparadores automáticos de escalamiento
-
-| Disparador | Acción | Plazo |
-|---|---|---|
-| Valor de devolución > $5,000 (un artículo) | Aprobación de supervisor antes del reembolso | Antes de procesar |
-| Puntuación de fraude ≥ 80 | Retener reembolso, enrutar al equipo de revisión de fraude | De inmediato |
-| Cliente presentó un contracargo simultáneamente | Detener procesamiento, coordinar con el equipo de pagos | En 1 hora |
-| Producto identificado con recall | Enrutar al coordinador de recall, no procesar como devolución estándar | De inmediato |
-| Tasa de defectos de proveedor excede 5% para un SKU | Notificar a merchandising y gestión de proveedores | En 24 horas |
-| Tercera solicitud de excepción del mismo cliente en 12 meses | Revisión gerencial antes de conceder | Antes de procesar |
-| Sospecha de falsificación en el flujo de devoluciones | Retirar del procesamiento, fotografiar, notificar a LP y protección de marca | De inmediato |
-| Devolución involucra producto regulado (farma, materiales peligrosos, dispositivo médico) | Enrutar al equipo de cumplimiento | De inmediato |
-
-### Cadena de escalamiento
-
-Nivel 1 (Asociado de Devoluciones) → Nivel 2 (Líder de Equipo, 2 horas) → Nivel 3 (Gerente de Devoluciones, 8 horas) → Nivel 4 (Director de Operaciones, 24 horas) → Nivel 5 (VP, 48+ horas o cualquier devolución de un solo artículo > $25K)
-
-## Indicadores de desempeño
-
-| Métrica | Meta | Bandera roja |
-|---|---|---|
-| Tiempo de procesamiento (recepción a reembolso) | < 48 horas | > 96 horas |
-| Precisión de inspección (acuerdo de grado en auditoría) | > 95% | < 88% |
-| Tasa de reposición (% devoluciones repuestas como nuevo/caja abierta) | > 45% | < 30% |
-| Tasa de detección de fraude (fraude confirmado atrapado) | > 80% | < 60% |
-| Tasa de falsos positivos (devoluciones legítimas marcadas) | < 3% | > 8% |
-| Tasa de recuperación con proveedor ($ recuperado / $ elegible) | > 70% | < 45% |
-| Satisfacción del cliente (CSAT post-devolución) | > 4.2/5.0 | < 3.5/5.0 |
-| Costo por devolución procesada | < $8.00 | > $15.00 |
-
-## Recursos adicionales
-
-- Combina esta skill con tu rúbrica de clasificación, umbrales de revisión de fraude y matriz de autoridad de reembolso antes de usarla en producción.
-- Mantén los estándares de reposición, el manejo de devoluciones de material peligroso y las reglas de liquidación cerca del equipo operativo que ejecutará las decisiones.
-
-## Nota
-
-Esta skill es una guía metodológica de operaciones. No sustituye la asesoría legal, fiscal, aduanera ni regulatoria; las decisiones sobre productos con recall, materiales peligrosos, devoluciones transfronterizas y productos regulados deben validarse con las personas responsables y calificadas de tu organización.

package/vendor/theus-arsenal/skills/manejo-errores/SKILL.md

@@ -1,375 +0,0 @@
----
-name: manejo-errores
-description: Patrones para un manejo de errores robusto en TypeScript, Python y Go. Cubre errores tipados, error boundaries, reintentos, circuit breakers y mensajes de error de cara al usuario.
----
-
-# Patrones de manejo de errores
-
-Patrones de manejo de errores consistentes y robustos para aplicaciones en producción.
-
-## Cuándo activarla
-
-- Al diseñar tipos de error o jerarquías de excepciones para un módulo o servicio nuevo
-- Al añadir lógica de reintentos o circuit breakers para dependencias externas poco fiables
-- Al revisar endpoints de API en busca de manejo de errores ausente
-- Al implementar mensajes de error y retroalimentación de cara al usuario
-- Al depurar fallos en cascada o errores silenciados
-
-## Principios fundamentales
-
-1. **Falla rápido y de forma visible** — haz aflorar los errores en el límite donde ocurren; no los entierres
-2. **Errores tipados antes que mensajes de texto** — los errores son valores de primera clase con estructura
-3. **Mensajes de usuario ≠ mensajes de desarrollador** — muestra texto amable al usuario, registra el contexto completo del lado del servidor
-4. **Nunca silencies errores** — cada bloque `catch` debe manejar, relanzar o registrar
-5. **Los errores forman parte del contrato de tu API** — documenta cada código de error que un cliente pueda recibir
-
-## TypeScript / JavaScript
-
-### Clases de error tipadas
-
-```typescript
-// Define una jerarquía de errores para tu dominio
-export class AppError extends Error {
-  constructor(
-    message: string,
-    public readonly code: string,
-    public readonly statusCode: number = 500,
-    public readonly details?: unknown,
-  ) {
-    super(message)
-    this.name = this.constructor.name
-    // Mantiene la cadena de prototipos correcta en JavaScript transpilado a ES5.
-    // Necesario para que las comprobaciones `instanceof` (p. ej., `error instanceof NotFoundError`)
-    // funcionen correctamente al extender la clase Error nativa.
-    Object.setPrototypeOf(this, new.target.prototype)
-  }
-}
-
-export class NotFoundError extends AppError {
-  constructor(resource: string, id: string) {
-    super(`${resource} not found: ${id}`, 'NOT_FOUND', 404)
-  }
-}
-
-export class ValidationError extends AppError {
-  constructor(message: string, details: { field: string; message: string }[]) {
-    super(message, 'VALIDATION_ERROR', 422, details)
-  }
-}
-
-export class UnauthorizedError extends AppError {
-  constructor(reason = 'Authentication required') {
-    super(reason, 'UNAUTHORIZED', 401)
-  }
-}
-
-export class RateLimitError extends AppError {
-  constructor(public readonly retryAfterMs: number) {
-    super('Rate limit exceeded', 'RATE_LIMITED', 429)
-  }
-}
-```
-
-### Patrón Result (estilo sin throw)
-
-Para operaciones donde el fallo es esperado y frecuente (parseo, llamadas externas):
-
-```typescript
-type Result<T, E = AppError> =
-  | { ok: true; value: T }
-  | { ok: false; error: E }
-
-function ok<T>(value: T): Result<T> {
-  return { ok: true, value }
-}
-
-function err<E>(error: E): Result<never, E> {
-  return { ok: false, error }
-}
-
-// Uso
-async function fetchUser(id: string): Promise<Result<User>> {
-  try {
-    const user = await db.users.findUnique({ where: { id } })
-    if (!user) return err(new NotFoundError('User', id))
-    return ok(user)
-  } catch (e) {
-    return err(new AppError('Database error', 'DB_ERROR'))
-  }
-}
-
-const result = await fetchUser('abc-123')
-if (!result.ok) {
-  // Aquí TypeScript sabe que existe result.error
-  logger.error('No se pudo obtener el usuario', { error: result.error })
-  return
-}
-// Aquí TypeScript sabe que existe result.value
-console.log(result.value.email)
-```
-
-### Manejador de errores de API (Next.js / Express)
-
-```typescript
-import { NextRequest, NextResponse } from 'next/server'
-
-function handleApiError(error: unknown): NextResponse {
-  // Error de aplicación conocido
-  if (error instanceof AppError) {
-    return NextResponse.json(
-      {
-        error: {
-          code: error.code,
-          message: error.message,
-          ...(error.details ? { details: error.details } : {}),
-        },
-      },
-      { status: error.statusCode },
-    )
-  }
-
-  // Error de validación de Zod
-  if (error instanceof z.ZodError) {
-    return NextResponse.json(
-      {
-        error: {
-          code: 'VALIDATION_ERROR',
-          message: 'Request validation failed',
-          details: error.issues.map(i => ({
-            field: i.path.join('.'),
-            message: i.message,
-          })),
-        },
-      },
-      { status: 422 },
-    )
-  }
-
-  // Error inesperado — registrar detalles, devolver mensaje genérico
-  console.error('Error inesperado:', error)
-  return NextResponse.json(
-    { error: { code: 'INTERNAL_ERROR', message: 'An unexpected error occurred' } },
-    { status: 500 },
-  )
-}
-
-export async function POST(req: NextRequest) {
-  try {
-    // ... lógica del handler
-  } catch (error) {
-    return handleApiError(error)
-  }
-}
-```
-
-### Error Boundary de React
-
-```typescript
-import { Component, ErrorInfo, ReactNode } from 'react'
-
-interface Props {
-  fallback: ReactNode
-  onError?: (error: Error, info: ErrorInfo) => void
-  children: ReactNode
-}
-
-interface State {
-  hasError: boolean
-  error: Error | null
-}
-
-export class ErrorBoundary extends Component<Props, State> {
-  state: State = { hasError: false, error: null }
-
-  static getDerivedStateFromError(error: Error): State {
-    return { hasError: true, error }
-  }
-
-  componentDidCatch(error: Error, info: ErrorInfo) {
-    this.props.onError?.(error, info)
-    console.error('Error de React no manejado:', error, info)
-  }
-
-  render() {
-    if (this.state.hasError) return this.props.fallback
-    return this.props.children
-  }
-}
-
-// Uso
-<ErrorBoundary fallback={<p>Algo salió mal. Por favor, recarga la página.</p>}>
-  <MyComponent />
-</ErrorBoundary>
-```
-
-## Python
-
-### Jerarquía de excepciones personalizada
-
-```python
-class AppError(Exception):
-    """Error base de la aplicación."""
-    def __init__(self, message: str, code: str, status_code: int = 500):
-        super().__init__(message)
-        self.code = code
-        self.status_code = status_code
-
-class NotFoundError(AppError):
-    def __init__(self, resource: str, id: str):
-        super().__init__(f"{resource} not found: {id}", "NOT_FOUND", 404)
-
-class ValidationError(AppError):
-    def __init__(self, message: str, details: list[dict] | None = None):
-        super().__init__(message, "VALIDATION_ERROR", 422)
-        self.details = details or []
-```
-
-### Manejador global de excepciones en FastAPI
-
-```python
-from fastapi import FastAPI, Request
-from fastapi.responses import JSONResponse
-
-app = FastAPI()
-
-@app.exception_handler(AppError)
-async def app_error_handler(request: Request, exc: AppError) -> JSONResponse:
-    return JSONResponse(
-        status_code=exc.status_code,
-        content={"error": {"code": exc.code, "message": str(exc)}},
-    )
-
-@app.exception_handler(Exception)
-async def generic_error_handler(request: Request, exc: Exception) -> JSONResponse:
-    # Registrar todos los detalles, devolver un mensaje genérico
-    logger.exception("Error inesperado", exc_info=exc)
-    return JSONResponse(
-        status_code=500,
-        content={"error": {"code": "INTERNAL_ERROR", "message": "An unexpected error occurred"}},
-    )
-```
-
-## Go
-
-### Errores centinela y envoltura de errores
-
-```go
-package domain
-
-import "errors"
-
-// Errores centinela para verificación de tipo
-var (
-    ErrNotFound    = errors.New("not found")
-    ErrUnauthorized = errors.New("unauthorized")
-    ErrConflict     = errors.New("conflict")
-)
-
-// Envuelve los errores con contexto — nunca pierdas el original
-func (r *UserRepository) FindByID(ctx context.Context, id string) (*User, error) {
-    user, err := r.db.QueryRow(ctx, "SELECT * FROM users WHERE id = $1", id)
-    if errors.Is(err, sql.ErrNoRows) {
-        return nil, fmt.Errorf("user %s: %w", id, ErrNotFound)
-    }
-    if err != nil {
-        return nil, fmt.Errorf("querying user %s: %w", id, err)
-    }
-    return user, nil
-}
-
-// A nivel del handler, desenvuelve para determinar la respuesta
-func (h *Handler) GetUser(w http.ResponseWriter, r *http.Request) {
-    user, err := h.service.GetUser(r.Context(), chi.URLParam(r, "id"))
-    if err != nil {
-        switch {
-        case errors.Is(err, domain.ErrNotFound):
-            writeError(w, http.StatusNotFound, "not_found", err.Error())
-        case errors.Is(err, domain.ErrUnauthorized):
-            writeError(w, http.StatusForbidden, "forbidden", "Access denied")
-        default:
-            slog.Error("error inesperado", "err", err)
-            writeError(w, http.StatusInternalServerError, "internal_error", "An unexpected error occurred")
-        }
-        return
-    }
-    writeJSON(w, http.StatusOK, user)
-}
-```
-
-## Reintentos con backoff exponencial
-
-```typescript
-interface RetryOptions {
-  maxAttempts?: number
-  baseDelayMs?: number
-  maxDelayMs?: number
-  retryIf?: (error: unknown) => boolean
-}
-
-async function withRetry<T>(
-  fn: () => Promise<T>,
-  options: RetryOptions = {},
-): Promise<T> {
-  const {
-    maxAttempts = 3,
-    baseDelayMs = 500,
-    maxDelayMs = 10_000,
-    retryIf = () => true,
-  } = options
-
-  let lastError: unknown
-
-  for (let attempt = 1; attempt <= maxAttempts; attempt++) {
-    try {
-      return await fn()
-    } catch (error) {
-      lastError = error
-      if (attempt === maxAttempts || !retryIf(error)) throw error
-
-      const jitter = Math.random() * baseDelayMs
-      const delay = Math.min(baseDelayMs * 2 ** (attempt - 1) + jitter, maxDelayMs)
-      await new Promise(resolve => setTimeout(resolve, delay))
-    }
-  }
-
-  throw lastError
-}
-
-// Uso: reintentar errores de red transitorios, no los 4xx
-const data = await withRetry(() => fetch('/api/data').then(r => r.json()), {
-  maxAttempts: 3,
-  retryIf: (error) => !(error instanceof AppError && error.statusCode < 500),
-})
-```
-
-## Mensajes de error de cara al usuario
-
-Mapea los códigos de error a mensajes legibles por humanos. Mantén los detalles técnicos fuera del texto visible al usuario.
-
-```typescript
-const USER_ERROR_MESSAGES: Record<string, string> = {
-  NOT_FOUND: 'No se pudo encontrar el elemento solicitado.',
-  UNAUTHORIZED: 'Inicia sesión para continuar.',
-  FORBIDDEN: 'No tienes permiso para hacer eso.',
-  VALIDATION_ERROR: 'Revisa los datos ingresados e inténtalo de nuevo.',
-  RATE_LIMITED: 'Demasiadas solicitudes. Espera un momento e inténtalo de nuevo.',
-  INTERNAL_ERROR: 'Algo salió mal de nuestro lado. Inténtalo de nuevo más tarde.',
-}
-
-export function getUserMessage(code: string): string {
-  return USER_ERROR_MESSAGES[code] ?? USER_ERROR_MESSAGES.INTERNAL_ERROR
-}
-```
-
-## Checklist de manejo de errores
-
-Antes de fusionar cualquier código que toque el manejo de errores:
-
-- [ ] Cada bloque `catch` maneja, relanza o registra — nada de silenciar errores
-- [ ] Los errores de la API siguen el envelope estándar `{ error: { code, message } }`
-- [ ] Los mensajes de cara al usuario no contienen stack traces ni detalles internos
-- [ ] El contexto completo del error se registra del lado del servidor
-- [ ] Las clases de error personalizadas extienden una base `AppError` con un campo `code`
-- [ ] Las funciones async hacen aflorar los errores a quien las llama — nada de "disparar y olvidar" sin fallback
-- [ ] La lógica de reintentos solo reintenta errores reintentables (no errores 4xx del cliente)
-- [ ] Los componentes React están envueltos en `ErrorBoundary` para errores de renderizado