@saulwade/swl-ses 1.4.0 → 1.4.1

package/habilidades/feynman-auditor-swl/recursos/preguntas-language-agnostic.md

@@ -0,0 +1,108 @@
+# Preguntas Feynman — Language-Agnostic
+
+28 preguntas organizadas en 7 categorías. Aplicar a cada función no trivial del módulo bajo auditoría.
+
+---
+
+## Q1 — Propósito
+
+**Q1.1** ¿Qué hace exactamente esta función y solo esta función? Si no puedo describirla en una oración sin usar "y", ¿tiene demasiadas responsabilidades?
+
+**Q1.2** ¿Cuál es el invariante que esta función garantiza al terminar? ¿El código lo garantiza de verdad o solo en el camino feliz?
+
+**Q1.3** ¿Hay alguna condición en que esta función debería rechazar la operación pero no lo hace? ¿Qué pasa si se la llama dos veces seguidas con los mismos argumentos?
+
+**Q1.4** ¿Esta función asume que el estado del sistema está en alguna condición particular antes de ejecutarse? ¿Dónde se verifica esa condición?
+
+---
+
+## Q2 — Orden de operaciones
+
+**Q2.1** ¿Importa el orden en que estas líneas se ejecutan? Si cambio el orden de dos líneas adyacentes, ¿el resultado es el mismo?
+
+**Q2.2** ¿Esta función lee un valor y luego lo modifica? Si algo cambia el valor entre la lectura y la escritura, ¿qué pasa?
+
+**Q2.3** ¿El cálculo de recompensa, crédito, o resultado se hace ANTES o DESPUÉS de actualizar el estado base? ¿Debería ser al revés?
+
+**Q2.4** ¿Si esta función llama a un sistema externo (BD, API, caché), el estado local ya está actualizado en ese momento? ¿El sistema externo puede ver un estado inconsistente?
+
+---
+
+## Q3 — Consistencia cross-función
+
+**Q3.1** ¿Qué tienen en común esta función y otra que hace algo similar? ¿Una tiene un guard o una actualización que la otra no tiene?
+
+**Q3.2** ¿Existe una función de "camino normal" y una de "camino de emergencia/admin"? ¿Ambas actualizan exactamente el mismo conjunto de estado?
+
+**Q3.3** ¿Esta función inicializa todos los campos que otras funciones esperan encontrar inicializados? ¿Hay algún campo que se lee antes de ser escrito?
+
+**Q3.4** ¿El path que crea un recurso y el path que lo elimina dejan el sistema en un estado simétrico? ¿O el delete deja huérfanos?
+
+---
+
+## Q4 — Asunciones implícitas
+
+**Q4.1** ¿Qué asume este código sobre el tipo o el rango del argumento que recibe? ¿Hay alguna validación que debería existir pero no existe?
+
+**Q4.2** ¿El código asume que el actor que llama esta función tiene permiso para hacerlo? ¿Dónde se verifica ese permiso exactamente?
+
+**Q4.3** ¿El código asume que algún recurso externo (BD, archivo, servicio) está disponible y en un estado consistente? ¿Qué pasa si no lo está?
+
+**Q4.4** ¿El código asume que nunca se llamará con valor cero, lista vacía, o string vacío? ¿Se validó eso?
+
+---
+
+## Q5 — Límites y casos de borde
+
+**Q5.1** ¿Qué pasa si el valor es exactamente cero? ¿Y si es el máximo representable? ¿Y si es negativo?
+
+**Q5.2** ¿Qué pasa si la lista o colección está vacía? ¿Y si tiene exactamente un elemento? ¿Y si tiene millones?
+
+**Q5.3** ¿Qué pasa si el recurso ya existe cuando se intenta crear? ¿Y si no existe cuando se intenta modificar o eliminar?
+
+**Q5.4** ¿Qué pasa si dos actores ejecutan esta función al mismo tiempo? ¿Hay condición de carrera? ¿El resultado es determinista?
+
+---
+
+## Q6 — Returns y manejo de errores
+
+**Q6.1** ¿Qué devuelve esta función cuando el input es inválido? ¿Lanza excepción, devuelve null, devuelve un error tipado, o silencia el problema?
+
+**Q6.2** ¿Si una operación parcial falla a mitad de camino, el estado queda consistente? ¿Hay rollback? ¿O el sistema queda a medias?
+
+**Q6.3** ¿El caller de esta función verifica el valor de retorno? ¿Un error no verificado puede causar daño silencioso más adelante?
+
+**Q6.4** ¿El código captura excepciones de forma demasiado amplia (`except Exception`, `catch (e)` vacío)? ¿Qué errores legítimos podría estar silenciando?
+
+---
+
+## Q7 — Interacciones externas
+
+**Q7.1** ¿Esta función llama a un sistema externo (BD, API, caché, cola)? ¿La llamada puede fallar? ¿Qué pasa con el estado local si falla?
+
+**Q7.2** ¿Esta función persiste datos en más de un lugar (ej: BD + caché + índice)? ¿Qué pasa si la segunda escritura falla después de que la primera tuvo éxito?
+
+**Q7.3** ¿El acumulador o índice que esta función usa se actualiza ANTES de modificar el valor base, o DESPUÉS? ¿El orden importa para la correctitud del cálculo?
+
+**Q7.4** ¿Esta función envía una notificación, evento, o mensaje a otro sistema? ¿Lo hace antes o después de confirmar la operación? ¿El receptor puede actuar sobre un estado que aún no se confirmó?
+
+**Q7.5** ¿Esta función lee un valor de caché y lo trata como fresco? ¿Hay algún path donde la caché puede estar desactualizada respecto a la fuente de verdad?
+
+**Q7.6** ¿Esta función modifica datos de otro actor además de los del actor que la llama? ¿Tiene permiso para hacerlo en todos los casos?
+
+**Q7.7** ¿Existe un patrón de acumulador donde el total acumulado se calcula con base en el estado anterior? Si el estado base cambia (insert/update/delete de otro registro), ¿el acumulador refleja el cambio correctamente?
+
+**Q7.8** ¿Esta función delega a otra función que tiene sus propios efectos secundarios? ¿El caller sabe qué estado modifica el callee internamente?
+
+---
+
+## Cómo usar estas preguntas
+
+1. Leer la función completa una vez para entender el propósito.
+2. Para cada pregunta de las categorías Q1–Q7, marcar:
+   - ✓ Respondida claramente por el código
+   - ? Requiere rastrear el caller o el sistema externo para responder
+   - ✗ El código no la responde — sospechoso de bug
+3. Todo `✗` o `?` sin resolver es un **sospechoso** para Fase 3 de síntesis.
+
+<!-- Adaptado de nemesis-auditor-main bajo MIT License (https://github.com/0xiehnnkta/nemesis-auditor) -->

package/habilidades/state-inconsistency-auditor-swl/SKILL.md

@@ -0,0 +1,166 @@
+---
+name: state-inconsistency-auditor-swl
+description: >
+  Encuentra bugs donde una operación muta un fragmento de estado acoplado sin
+  actualizar su contraparte dependiente, causando corrupción silenciosa o fallos
+  en operaciones posteriores. Mapea sistemáticamente pares de estado acoplado,
+  todos sus paths de mutación, y los gaps donde un lado se actualiza sin el otro.
+  Language-agnostic (Python, TS, Go, Rust, Java, C#). Cargar cuando se sospeche
+  estado desincronizado: caché obsoleta, índices secundarios huérfanos, contadores
+  que no coinciden con la suma de sus partes, o permisos derivados que no reflejan
+  el estado de origen.
+---
+
+# Cuándo cargar
+
+- Sospechas que un caché, índice secundario, o contador agregado está desincronizado.
+- Una función actualiza la tabla principal pero no el índice derivado.
+- Hay paths de "emergencia" o "admin" que modifican estado sin pasar por el flujo normal.
+- Nemesis está corriendo su Pasada 2.
+
+# Cuándo NO cargar
+
+- Para búsqueda de vulnerabilidades conocidas (inyección SQL, XSS) — usar `revisor-seguridad-swl`.
+- Para revisión de lógica de función individual sin estado acoplado — usar `feynman-auditor-swl`.
+- Para módulos sin persistencia de estado (transformaciones funcionales puras, utilería).
+
+---
+
+# State Inconsistency Auditor
+
+Encuentra bugs donde una operación actualiza State A sin actualizar State B, cuando el invariante del sistema exige que ambos cambien juntos.
+
+Los patrones detallados de estado acoplado están en [recursos/coupled-state-patterns.md](recursos/coupled-state-patterns.md).
+
+---
+
+## El patrón abstracto
+
+Todo sistema mantiene **PARES DE ESTADO ACOPLADO**: dos o más valores de almacenamiento que deben mantener una relación (un invariante) entre sí. Cuando cualquier operación cambia un lado del par sin ajustar el otro, el invariante se rompe. Operaciones posteriores que leen ambos valores producen resultados incorrectos.
+
+---
+
+## Reglas del auditor
+
+```
+REGLA 0: MAPEAR ANTES DE CAZAR
+Nunca empezar a revisar funciones sin tener el mapa completo de
+dependencias de estado acoplado. No se puede encontrar una actualización
+faltante si no se sabe qué actualizaciones son necesarias.
+
+REGLA 1: TODOS LOS PATHS DE MUTACIÓN IMPORTAN
+Una variable de estado puede modificarse desde 5 funciones distintas.
+Las 5 deben actualizar el estado acoplado. Si 4 lo hacen y 1 no — ese es el bug.
+
+REGLA 2: LAS OPERACIONES PARCIALES SON LA FUENTE #1
+Las eliminaciones completas (eliminar todo) generalmente resetean todo el estado
+correctamente. Las operaciones parciales (reducir en X) frecuentemente olvidan
+reducir proporcionalmente el estado acoplado.
+
+REGLA 3: COMPARAR PATHS PARALELOS
+Si transferir() y eliminar() ambos reducen un balance, AMBOS deben actualizar
+el mismo conjunto de estado acoplado. Si uno lo hace y el otro no — hallazgo.
+
+REGLA 4: EL CÓDIGO DEFENSIVO ENMASCARA BUGS
+Código como `valor > minimo ? valor - minimo : 0` o `min(calculado, disponible)`
+oculta invariantes rotos silenciosamente. Son señales de alerta, no protecciones.
+
+REGLA 5: SOLO HALLAZGOS BASADOS EN EVIDENCIA
+Todo hallazgo debe incluir: el par acoplado, la operación que lo rompe,
+una secuencia de trigger concreta, y la consecuencia observable.
+```
+
+---
+
+## Proceso
+
+### Fase 1: Mapear pares de estado acoplado
+
+Para cada variable de almacenamiento, preguntar: **"¿Qué otros valores de almacenamiento deben cambiar cuando este cambia?"**
+
+Construir un mapa de dependencias. Ver patrones comunes en `recursos/coupled-state-patterns.md`.
+
+Salida de Fase 1: **Mapa de Dependencias de Estado Acoplado**.
+
+### Fase 2: Matriz de mutación
+
+Para cada variable identificada en Fase 1, listar TODAS las funciones y paths de código que la modifican. Incluir: escrituras directas, incrementos/decrementos, eliminaciones, mutaciones indirectas (llamadas internas), triggers externos (callbacks, hooks).
+
+Marcar con `???` toda entrada donde no se ha confirmado si la contraparte acoplada también se actualiza.
+
+Los `???` son los **objetivos primarios de auditoría**.
+
+### Fase 3: Cross-check — el corazón de la auditoría
+
+Para cada par (operación, variable de estado) de Fase 2:
+
+> "Esta operación modifica State A. ¿También actualiza todo el estado acoplado que depende de A?"
+
+Verificar específicamente:
+- Eliminación completa (A → 0): ¿se resetea/limpia todo el estado acoplado?
+- Eliminación parcial (A decrece): ¿se reduce proporcionalmente todo el estado acoplado?
+- Incremento (A crece): ¿se incrementa proporcionalmente todo el estado acoplado?
+- Transferencia (A se mueve entre entidades): ¿el estado acoplado se mueve también?
+- Eliminación de entrada de colección: ¿la entrada del par también se elimina?
+- Operación en lote: ¿el estado acoplado se actualiza por iteración o solo una vez?
+
+**Si algún path actualiza A sin actualizar su estado acoplado → HALLAZGO.**
+
+### Fase 4: Orden de operaciones dentro de funciones
+
+Muchas funciones realizan múltiples cambios de estado en secuencia. Rastrear el orden exacto y preguntar en cada paso: "¿Después de este paso, todos los pares acoplados siguen siendo consistentes?"
+
+Bugs de orden comunes:
+- Calcular resultado ANTES de actualizar el índice → resultado usa estado obsoleto
+- Leer caché DESPUÉS de modificar el origen → validación usa datos viejos
+- Emitir evento con valores viejos DESPUÉS del cambio de estado → sistemas externos se desincronizarán
+
+### Fase 5: Comparar paths paralelos
+
+Encontrar operaciones que logran resultados similares por paths distintos. Para cada grupo, comparar: ¿TODOS los paths actualizan el mismo estado acoplado?
+
+### Fase 6: Rastrear journeys multi-paso
+
+Simular secuencias donde un actor interactúa múltiples veces:
+
+1. Actor inicializa un recurso (estado inicializado)
+2. Tiempo pasa / estado externo evoluciona
+3. Actor hace modificación PARCIAL (el estado acoplado puede romperse aquí)
+4. Más tiempo pasa
+5. Actor hace otra operación que lee el estado acoplado
+
+En el paso 5: ¿el estado acoplado sigue siendo válido dado el cambio parcial del paso 3?
+
+### Fase 7: Patrones de enmascaramiento
+
+El código defensivo puede ocultar invariantes rotos. Ver patrones en `recursos/coupled-state-patterns.md`.
+
+Señal: si un ternario del tipo `a > b ? a - b : 0` está en un cálculo que involucra dos valores acoplados, preguntar: ¿por qué `a` podría ser menor que `b`? Si el invariante se mantuviera, no podría.
+
+---
+
+## Verificación (obligatoria para C/A/M)
+
+**Método A: Rastreo de código** — leer la función exacta, rastrear todas las llamadas internas, confirmar que no existe actualización oculta al estado acoplado.
+
+**Método B: Test de PoC** — escribir un test que ejecute la secuencia de trigger y afirme que el estado es inconsistente después de la operación.
+
+**Método C: Híbrido** — rastreo + PoC para hallazgos que abarcan múltiples módulos.
+
+**Falsos positivos frecuentes:**
+- Reconciliación oculta en un hook `_before_save` / `_after_update` / middleware.
+- Evaluación diferida intencional: el estado acoplado se reconcilia en la próxima lectura.
+- Asimetría de diseño documentada: los dos estados no son realmente acoplados como se asumió.
+
+---
+
+## Adaptación por lenguaje
+
+| Concepto | Python | TypeScript | Go | Rust | Java | C# |
+|---------|--------|------------|-----|------|------|-----|
+| Almacenamiento | atributos / BD | propiedades / BD | campos struct / BD | campos struct | campos clase | propiedades |
+| Colección clave-valor | `dict` / `HashMap` Redis | `Map` / objeto | `map[K]V` | `HashMap` | `Map<K,V>` | `Dictionary<K,V>` |
+| Eliminar entrada | `del d[k]` / `pop` | `delete obj[k]` | `delete(m, k)` | `map.remove(&k)` | `map.remove(k)` | `dict.Remove(k)` |
+| Hook post-mutación | `@receiver` / signal | middleware / hook | middleware | `impl Drop` / hook | `@PostUpdate` | event handler |
+
+<!-- Adaptado de nemesis-auditor-main bajo MIT License (https://github.com/0xiehnnkta/nemesis-auditor) -->

package/habilidades/state-inconsistency-auditor-swl/recursos/coupled-state-patterns.md

@@ -0,0 +1,147 @@
+# Patrones de Estado Acoplado — Language-Agnostic
+
+9 patrones de estado acoplado frecuentes en sistemas Python, TypeScript, Go, Rust, Java y C#.
+
+---
+
+## Patrón 1: Balance ↔ Caché derivada
+
+**Descripción**: un valor base (balance de cuenta, stock de inventario, crédito disponible) tiene una caché calculada a partir de él (porcentaje disponible, categoría de riesgo, tier de cliente).
+
+**Invariante**: la caché debe reflejar el balance actual, no el del momento en que se calculó.
+
+**Paths de mutación riesgosos**: cualquier operación que modifica el balance directamente sin pasar por el flujo que actualiza la caché.
+
+**Trigger típico**: función de ajuste manual, importación masiva, o corrección administrativa que escribe el balance sin llamar al servicio que recalcula la caché.
+
+**Consecuencia**: decisiones que leen la caché (¿aplica descuento? ¿otorgar crédito?) usan datos obsoletos.
+
+---
+
+## Patrón 2: Registro principal ↔ Índice secundario
+
+**Descripción**: una tabla o colección tiene un índice secundario (índice invertido, tabla de búsqueda rápida, lista de IDs por categoría) que debe estar sincronizado con la tabla principal.
+
+**Invariante**: toda entrada en la tabla principal tiene exactamente una entrada correspondiente en el índice secundario (o exactamente ninguna, según el diseño).
+
+**Paths de mutación riesgosos**: delete de la tabla principal sin delete del índice; insert sin insert correspondiente; update que cambia la clave del índice sin actualizar el índice.
+
+**Trigger típico**: función de "purga" o "limpieza" que borra de la tabla principal pero olvida el índice. O migración que popula la tabla principal pero no regenera el índice.
+
+**Consecuencia**: búsquedas por índice devuelven resultados incorrectos (IDs que ya no existen, o registros que no aparecen en búsqueda aunque existan).
+
+---
+
+## Patrón 3: Contador agregado ↔ Suma de partes
+
+**Descripción**: un contador de totales (total de pedidos, total de puntos, total de items activos) debe ser igual a la suma de los contadores individuales.
+
+**Invariante**: `total == sum(individuales)` siempre.
+
+**Paths de mutación riesgosos**: operaciones que modifican un contador individual sin ajustar el total. Frecuente en operaciones de batch donde el total se actualiza una sola vez al final pero un error parcial deja los individuales en estado inconsistente.
+
+**Trigger típico**: transacción fallida a mitad que actualiza N de M elementos pero no revierte el total; o función que incrementa directamente el conteo individual sin notificar al agregador.
+
+**Consecuencia**: reportes y dashboards muestran cifras incorrectas; límites y cuotas se aplican con base en datos erróneos.
+
+---
+
+## Patrón 4: Sesión / Permiso derivado ↔ Recurso de origen
+
+**Descripción**: un objeto de sesión, token, o permiso derivado almacena un snapshot de los permisos o atributos del actor al momento de su creación. El actor puede cambiar después.
+
+**Invariante**: depende del diseño. Si los permisos se evalúan en tiempo de solicitud, el objeto derivado debe reflejar el estado actual del actor. Si se usan permisos fijados al momento de creación, el invariante es documentado explícitamente.
+
+**Paths de mutación riesgosos**: revocar permisos al actor sin invalidar sesiones activas; cambiar el rol del actor sin forzar re-autenticación; eliminar al actor sin expirar sus tokens.
+
+**Trigger típico**: función de "deshabilitar cuenta" que setea `is_active=False` en el usuario pero no invalida los tokens JWT o sesiones existentes.
+
+**Consecuencia**: actor deshabilitado sigue operando hasta que el token expira naturalmente.
+
+---
+
+## Patrón 5: Posición ↔ Factor de salud cacheado
+
+**Descripción**: un recurso con múltiples atributos (posición de deuda: monto + colateral + fecha + valor de mercado del colateral) tiene un factor calculado (ratio LTV, score de riesgo, estado de salud) que se cachea por rendimiento.
+
+**Invariante**: el factor cacheado debe recalcularse cada vez que cualquiera de sus inputs cambia.
+
+**Paths de mutación riesgosos**: actualizar cualquier input del cálculo sin invalidar o recalcular el factor cacheado.
+
+**Trigger típico**: función que actualiza el colateral sin llamar a `recalcular_factor()`. O función de ajuste de precio que modifica el valor de mercado sin propagar la invalidación de caché.
+
+**Consecuencia**: decisiones de riesgo (¿emitir alerta? ¿bloquear operación?) usan un factor obsoleto.
+
+---
+
+## Patrón 6: Replica / Proyección ↔ Origen CDC
+
+**Descripción**: un sistema mantiene una replica o proyección de datos de origen para acelerar lecturas (tabla denormalizada, proyección CQRS, replica de lectura, caché materializada). El origen puede cambiar vía CDC (Change Data Capture), eventos de dominio, o sincronización periódica.
+
+**Invariante**: la replica debe converger al estado del origen dentro de la ventana de latencia acordada.
+
+**Paths de mutación riesgosos**: escrituras directas al origen que no emiten el evento de dominio necesario para actualizar la replica; fallos en el consumer de eventos que quedan silenciosos; migraciones que modifican el origen sin reprocesar los eventos para actualizar la replica.
+
+**Trigger típico**: endpoint de "corrección de datos" que escribe directo a la BD origen sin publicar el evento de dominio correspondiente.
+
+**Consecuencia**: lecturas de la replica devuelven datos obsoletos indefinidamente.
+
+---
+
+## Patrón 7: Inventario total ↔ Items en almacén (por ubicación)
+
+**Descripción**: el inventario total de un SKU es la suma de los items en cada almacén o ubicación. Se mantiene desnormalizado por rendimiento.
+
+**Invariante**: `inventario_total[SKU] == sum(items_por_ubicacion[ubicacion][SKU] for ubicacion in todas)`
+
+**Paths de mutación riesgosos**: movimiento entre almacenes que decrementa una ubicación sin incrementar la otra; recepción en almacén sin incrementar el total; ajuste de inventario físico que corrige la ubicación sin propagar al total.
+
+**Trigger típico**: función de "ajuste de cierre" que actualiza el stock físico de un almacén sin pasar por la capa de negocio que mantiene el total sincronizado.
+
+**Consecuencia**: órdenes de compra se emiten sobre stock inexistente; o stock disponible no se vende por parecer agotado.
+
+---
+
+## Patrón 8: Estado de workflow ↔ Timestamps de auditoría
+
+**Descripción**: una entidad con workflow (pedido, solicitud, tarea) almacena su estado actual y los timestamps de cada transición. El timestamp de la última transición debe corresponder al estado actual.
+
+**Invariante**: `estado_actual` siempre tiene un timestamp asociado que refleja cuándo se alcanzó ese estado.
+
+**Paths de mutación riesgosos**: funciones que cambian el estado sin registrar el timestamp; o funciones que registran el timestamp sin actualizar el estado.
+
+**Trigger típico**: función de "forzar estado" en panel de administración que escribe `estado = 'COMPLETADO'` directamente sin pasar por la máquina de estados que registra `completado_en = now()`.
+
+**Consecuencia**: reportes de tiempo de ciclo son incorrectos; SLAs no se calculan bien; auditorías de cumplimiento fallan.
+
+---
+
+## Patrón 9: Configuración global ↔ Snapshot por instancia
+
+**Descripción**: hay una configuración global (tasa de impuesto, precio de tarifa, límite de política) y objetos que almacenan el valor que tenía la configuración en el momento de su creación (tasa de impuesto aplicada a esta factura, precio de tarifa al momento de la reserva).
+
+**Invariante**: el snapshot por instancia debe preservar el valor histórico, nunca actualizarse cuando cambia la configuración global. Pero si hay un bug en la creación, el snapshot puede haber capturado un valor incorrecto.
+
+**Paths de mutación riesgosos**: función que no captura el snapshot al crear la instancia y usa la configuración global en tiempo de lectura; o función de retroactiva que sobreescribe snapshots históricos con el valor actual de la configuración.
+
+**Trigger típico**: migración de datos que "normaliza" snapshots históricos al valor actual de la configuración global, destruyendo la trazabilidad.
+
+**Consecuencia**: recálculos retroactivos producen cifras incorrectas; auditorías de facturación no reproducen los valores originales.
+
+---
+
+## Patrones de enmascaramiento
+
+Código defensivo que oculta invariantes rotos en lugar de detectarlos:
+
+| Patrón | Código típico | Por qué es señal de alerta |
+|--------|--------------|---------------------------|
+| Ternario de clamp | `a > b ? a - b : 0` | Si el invariante se mantuviera, `a` nunca sería menor que `b` |
+| Try/catch vacío | `try { ... } catch {}` | El revert por estado roto se captura y se ignora |
+| Early exit en cero | `if value == 0: return` | Omite el cómputo cuando el estado roto produce cero |
+| Cap con min() | `min(calculado, disponible)` | El over-counting es el bug; `min()` solo evita el error visible |
+| Fallback a default | `valor = d.get(k, 0)` | Si la key debería existir pero fue eliminada sin limpiar el par, el default enmascara el dato faltante |
+
+Cuando se encuentra cualquiera de estos patrones en código que involucra dos valores acoplados, rastrear si el patrón existe porque el invariante ya estaba roto en algún path de mutación.
+
+<!-- Adaptado de nemesis-auditor-main bajo MIT License (https://github.com/0xiehnnkta/nemesis-auditor) -->

package/habilidades/web-fetcher-routing/SKILL.md

@@ -0,0 +1,75 @@
+---
+name: web-fetcher-routing
+description: >
+  Routing inteligente para fetching de URLs según dominio y formato:
+  GitHub raw, PDF, sitios JS-heavy y default. Reduce tokens consumidos
+  evitando WebFetch cuando hay alternativa más eficiente. Cargar antes
+  de hacer WebFetch a URLs externas, especialmente repositorios GitHub,
+  PDFs públicos, o sitios con paywall/Cloudflare/JS heavy.
+---
+
+# web-fetcher-routing
+
+Selecciona la herramienta correcta para cada URL antes de intentar el fetch.
+Un WebFetch al HTML de GitHub UI consume 10-30× más tokens que leer el raw.
+Un PDF vía Read devuelve basura binaria. La elección equivocada cuesta tokens
+reales; este skill la automatiza.
+
+## Cuándo cargar
+
+- Antes de hacer `WebFetch` a cualquier URL externa no trivial.
+- Cuando la URL apunta a GitHub (repositorio, archivo o blob).
+- Cuando la URL termina en `.pdf` o el contexto indica documento PDF.
+- Cuando el fetch previo falló con 402, página de login o contenido vacío
+  (señal de JS-heavy o Cloudflare).
+
+## Cuándo NO cargar
+
+- URLs internas del proyecto o localhost — usar `Read` directamente.
+- Contenido ya cargado en el contexto de esta sesión — no re-fetchar.
+- Cuando el usuario dictó explícitamente la herramienta a usar
+  ("usa WebFetch", "lee con curl").
+
+## Tabla de routing
+
+| Patrón de URL | Herramienta | Razón |
+|---|---|---|
+| `github.com/[user]/[repo]/blob/[branch]/[path]` | Reescribir a `raw.githubusercontent.com/[user]/[repo]/[branch]/[path]` y hacer `WebFetch` con la URL reescrita | Evita el HTML de la UI de GitHub; 10-30× menos tokens |
+| `raw.githubusercontent.com/...` | `WebFetch` directo | Ya es raw content |
+| URL termina en `.pdf` | Invocar `Skill("swl-markitdown")` para conversión con `pdftotext` o `markitdown` | `Read` no soporta PDF; `WebFetch` devuelve binario o HTML de visor |
+| `x.com`, `twitter.com`, cualquier host con CAPTCHA o Cloudflare detectado | Invocar `Skill("agent-browser")` con headless Chrome | `WebFetch` devuelve 402 o página de login; `agent-browser` usa accessibility tree (~82% menos tokens que screenshots) |
+| `mp.weixin.qq.com`, `feishu.cn`, `larksuite.com` | Invocar `Skill("agent-browser")` | Plataformas chinas con autenticación o JS requerido |
+| Todo lo demás | `WebFetch` directo | El caso común; probar primero antes de escalar |
+
+## Algoritmo de decisión
+
+1. Parsear la URL: extraer esquema, dominio y extensión del path.
+2. Comparar con los patrones de la tabla, en orden de arriba hacia abajo.
+3. Si el dominio es `github.com` con segmento `/blob/` en el path:
+   reescribir la URL antes de hacer el fetch.
+4. Invocar la herramienta asignada al patrón que coincide.
+5. Si el resultado tiene señales de paywall o error (primeras 10 líneas
+   contienen "Subscribe", "Sign in", "403", página vacía): escalar al
+   patrón JS-heavy con `Skill("agent-browser")`.
+6. Reportar qué método se usó y por qué, en una línea antes del contenido.
+
+## Ejemplo de reescritura GitHub
+
+```
+# URL original
+https://github.com/tw93/Waza/blob/main/skills/read/SKILL.md
+
+# URL reescrita para raw
+https://raw.githubusercontent.com/tw93/Waza/main/skills/read/SKILL.md
+```
+
+## Señales de fallo que activan escalado
+
+| Señal en la respuesta | Acción |
+|---|---|
+| HTTP 402 | Escalar a `agent-browser` |
+| Primeras líneas con "Sign in" o "Subscribe" | Detener, avisar al usuario |
+| Contenido HTML con menos de 200 caracteres | Reintentar con método alternativo |
+| Binario o caracteres ilegibles | Verificar si es PDF; si sí, usar `swl-markitdown` |
+
+<!-- Adaptado de Waza/skills/read bajo MIT License (tw93/Waza) -->