@saulwade/swl-ses 1.0.0

package/habilidades/swl-markitdown/evals/evals.json

@@ -0,0 +1,52 @@
+{
+  "$schema": "../../../schemas/skill-evals.schema.json",
+  "skill_name": "swl-markitdown",
+  "artifact_type": "skill",
+  "schema_version": 1,
+  "description": "Evals para swl-markitdown — conversión de formatos no-Markdown a Markdown.",
+  "evals": [
+    {
+      "id": 0,
+      "prompt": "Comando minimal para leer el contenido de `docs/spec.docx`.",
+      "files": [],
+      "expectations": [
+        "Usa `python scripts/vendor/markitdown/cli.py docs/spec.docx` (o equivalente `markitdown docs/spec.docx`).",
+        "NO sugiere `cat`, `Read`, ni `head` para .docx.",
+        "Menciona que el Read tool NO soporta .docx."
+      ],
+      "tags": ["primary-flow"],
+      "weight": 1.5
+    },
+    {
+      "id": "anti-substitution-pdf-small",
+      "prompt": "Tengo `docs/quickguide.pdf` de 3 páginas. ¿Qué herramienta uso?",
+      "files": [],
+      "expectations": [
+        "La respuesta sugiere Read tool con `pages:` (no markitdown).",
+        "La respuesta menciona que PDFs ≤20 páginas van por Read."
+      ],
+      "grading_guidance": "Failure si sugiere markitdown para PDF pequeño.",
+      "tags": ["anti-pattern"]
+    },
+    {
+      "id": "pdf-large",
+      "prompt": "Tengo `docs/manual.pdf` de 150 páginas con tablas. ¿Qué herramienta uso?",
+      "files": [],
+      "expectations": [
+        "La respuesta sugiere markitdown (no Read).",
+        "La respuesta menciona que markitdown extrae tablas como Markdown."
+      ],
+      "tags": ["primary-flow"]
+    },
+    {
+      "id": "jupyter",
+      "prompt": "¿Cómo leo un notebook Jupyter `.ipynb`?",
+      "files": [],
+      "expectations": [
+        "Usa markitdown (no Read).",
+        "Menciona que Read devuelve JSON crudo del notebook (no legible)."
+      ],
+      "tags": ["primary-flow"]
+    }
+  ]
+}

package/habilidades/swl-revisar-impacto/SKILL.md

@@ -0,0 +1,233 @@
+---
+name: swl-revisar-impacto
+description: >
+  Analiza el impacto de cambios en el codebase usando code-review-graph.
+  Ejecuta get_minimal_context → risk_score → get_impact_radius → detect_changes.
+  Activa cuando el usuario quiere saber qué se ve afectado por un cambio,
+  antes de modificar un componente crítico, o para análisis de riesgo pre-commit.
+user-invocable: false
+version: "1.0.0"
+herramientasPermitidas: [Read, Bash]
+exclusiones:
+  - "No cargar si el grafo `code-review-graph` no está disponible (`.code-review-graph/graph.db` ausente) — sin grafo construido el skill retorna MISSING en el prerequisito y no puede ejecutar ningún análisis."
+  - "No cargar para revisar calidad de código (linting, estilo, cobertura de tests) — eso es `calidad-pre-commit.js` o `/swl:revisar`; este skill evalúa impacto estructural en el grafo de dependencias."
+  - "No cargar en proyectos con codebase < 500 LOC o sin dependencias cruzadas significativas — el grafo de comunidades y blast radius no aportan información útil si el proyecto no tiene estructura modular suficiente."
+  - "No cargar para analizar impacto de cambios en documentación, SKILL.md o archivos de configuración que no tienen nodos en el grafo de código — el grafo solo indexa código fuente con llamadas/importaciones."
+evolvable: true  # default para skill estandar
+---
+# Skill: swl-revisar-impacto
+
+Analiza el impacto estructural de cambios usando el knowledge graph persistente
+del codebase (code-review-graph). Proporciona blast radius, risk score y flujos
+afectados antes de aplicar modificaciones.
+
+## Prerequisito — Verificar grafo disponible
+
+```bash
+PROJECT_ROOT=$(git rev-parse --show-toplevel 2>/dev/null || pwd)
+python -c "
+import sys, os
+db = os.path.join('$PROJECT_ROOT', '.code-review-graph', 'graph.db')
+print('OK' if os.path.exists(db) else 'MISSING')
+"
+```
+
+Si dice MISSING:
+```
+⚠ El grafo de código no está inicializado.
+  Ejecuta primero: /swl:revisar-impacto build
+  O directamente: python -c "import sys; sys.argv=['crg','build']; from code_review_graph.cli import main; main()"
+```
+
+## Subcomandos
+
+### `build` — Construir/reconstruir el grafo
+
+```bash
+PROJECT_ROOT=$(git rev-parse --show-toplevel 2>/dev/null || pwd)
+cd "$PROJECT_ROOT" && python -c "
+import sys
+sys.argv = ['code-review-graph', 'build']
+from code_review_graph.cli import main
+main()
+"
+```
+
+Mostrar al usuario:
+```
+Grafo construido:
+  Archivos:  {N}
+  Nodos:     {N}
+  Edges:     {N}
+  Lenguajes: {lista}
+  Actualizado: {ts}
+```
+
+### `status` — Estado actual del grafo
+
+```bash
+PROJECT_ROOT=$(git rev-parse --show-toplevel 2>/dev/null || pwd)
+cd "$PROJECT_ROOT" && python -c "
+import sys
+sys.argv = ['code-review-graph', 'status']
+from code_review_graph.cli import main
+main()
+"
+```
+
+### `contexto` (o vacío) — Análisis de riesgo general
+
+Obtiene el contexto mínimo de riesgo actual (~100 tokens):
+
+Usar la herramienta MCP `get_minimal_context` con:
+```json
+{ "task": "review", "detail_level": "minimal" }
+```
+
+Mostrar resultado al usuario:
+```
+Estado del grafo:
+  Nodos: {N} | Edges: {N} | Archivos: {N}
+  Lenguajes: {lista}
+
+Riesgo actual: {low | medium | high} ({score:.2f})
+
+Archivos afectados top:
+  - {nombre_función}: {razón}
+
+Test gaps: {N} funciones sin cobertura de tests
+
+Comunidades activas: {top 3}
+Flujos críticos: {top 3}
+
+Siguiente paso sugerido:
+  {tool_suggestion_1}
+  {tool_suggestion_2}
+```
+
+### `impacto <archivo_o_función>` — Blast radius de un componente
+
+Determinar el nodo a analizar: si el usuario proveyó un nombre de archivo o función,
+buscar su qualified_name en el grafo.
+
+Usar la herramienta MCP `get_impact_radius` con:
+```json
+{
+  "node_name": "<qualified_name>",
+  "depth": 3,
+  "detail_level": "standard"
+}
+```
+
+Mostrar al usuario:
+```
+Blast radius de {nombre}:
+  Impacto directo ({N} nodos):
+    - {nodo_1}: {tipo} ({archivo}:{línea})
+    - {nodo_2}: ...
+  
+  Impacto transitivo (profundidad 3):
+    - {N} nodos adicionales
+  
+  Tests que cubren este nodo: {N}
+  Tests en riesgo: {lista}
+  
+  ⚠ Modificar este nodo afecta {N_total} componentes del sistema.
+```
+
+Si N_total > 20: mostrar advertencia de alto impacto y sugerir `/swl:checkpoint` antes de proceder.
+
+### `cambios` — Análisis de riesgo de cambios actuales (pre-commit)
+
+Usar la herramienta MCP `detect_changes` con:
+```json
+{ "detail_level": "standard" }
+```
+
+Mostrar al usuario:
+```
+Análisis de cambios actuales:
+  Risk score: {score:.2f} ({low|medium|high})
+  
+  Funciones modificadas ({N}):
+    - {función}: riesgo {score} — {razón}
+  
+  Funciones sin tests ({N}):
+    - {función} ({archivo}:{línea})
+  
+  Flujos afectados ({N}):
+    - {flujo}: criticidad {score}
+  
+  {si risk_score > 0.7}
+  ⛔ RIESGO ALTO — Se recomienda:
+    1. Ejecutar /swl:checkpoint antes de continuar
+    2. Revisar cobertura de tests en funciones modificadas
+    3. Confirmar con el usuario antes del commit
+```
+
+### `comunidades` — Ver estructura modular del codebase
+
+Usar la herramienta MCP `list_communities` con:
+```json
+{ "detail_level": "standard" }
+```
+
+Mostrar tabla de comunidades:
+```
+Comunidades detectadas ({N}):
+  ID  | Nombre              | Nodos | Cohesión | Acoplamiento
+  ----|---------------------|-------|----------|-------------
+  1   | gateway-core        | 45    | 0.91     | 0.23
+  2   | hooks-observability | 38    | 0.87     | 0.31
+  ...
+
+Comunidades con alto acoplamiento (> 0.6): candidatas a refactor
+Comunidades con alta cohesión (> 0.8): estables — no tocar sin análisis
+```
+
+### `flujos` — Ver flujos de ejecución críticos
+
+Usar la herramienta MCP `list_flows` con:
+```json
+{ "detail_level": "standard", "limit": 10 }
+```
+
+Mostrar flujos ordenados por criticidad:
+```
+Flujos críticos del sistema (top 10):
+  1. {nombre_flujo} — criticidad: {score}
+     Entry point: {función}:{archivo}
+     Nodos: {N} | Terminales: {N}
+  ...
+```
+
+## Integración con flujo de trabajo SWL
+
+Invocar automáticamente este skill en estos momentos:
+1. **Antes de modificar agentes críticos** (orquestador, implementador, ejecutar-fase)
+2. **Antes de un release** (`/swl:release`) para detectar cambios riesgosos
+3. **Cuando el pre-commit bloquea** con risk score alto
+4. **Durante auto-evolución** para priorizar qué módulo optimizar primero
+
+## Relación con otros componentes
+
+| Componente       | Scope                          | Complemento                          |
+|------------------|--------------------------------|--------------------------------------|
+| `/swl:metricas`  | Costo/tokens de sesión actual  | revisar-impacto agrega análisis estructural |
+| `calidad-pre-commit.js` | Lint + secretos pre-commit | revisar-impacto agrega risk score semántico |
+| `auto-evolucion-swl` | Mejora de agentes         | revisar-impacto prioriza por comunidades |
+| `run-log.js`     | Observabilidad de sesión       | revisar-impacto agrega contexto de código |
+
+## Cuándo NO cargar
+
+- El prerequisito del Paso 0 retorna MISSING — sin `graph.db` construido, ningún subcomando funciona; primero construir el grafo con `code-review-graph`.
+- El objetivo es revisar calidad de código (lint, style, cobertura) — usar `/swl:revisar` o `calidad-pre-commit.js`; este skill evalúa blast radius estructural, no issues de calidad.
+- El proyecto es pequeño (< 500 LOC, sin módulos bien separados) — el análisis de comunidades y flujos críticos no aporta información útil cuando casi todo el código está acoplado en un único módulo.
+- Los archivos modificados son documentación, SKILL.md o configuración YAML — el grafo solo indexa código fuente con llamadas e importaciones; los cambios a archivos no-código no tienen nodos en el grafo.
+
+## Gotchas / Errores comunes no obvios
+
+- **`get_minimal_context` retorna nodos con `qualified_name` diferente al nombre de la función en el código**: el grafo indexa nombres calificados (ej. `api.routes.facturas.crear_factura`) mientras el código usa el nombre simple. Causa: el grafo usa el path completo como identificador de nodo. Solución: para el subcomando `impacto`, usar `get_minimal_context` primero para obtener el `qualified_name` correcto del nodo antes de pasar a `get_impact_radius` — nunca construir el qualified_name a mano.
+- **Blast radius N_total inflado por nodos de tipo "import" sin dependencia real**: el grafo muestra 40 nodos afectados pero la mayoría son módulos que solo importan el paquete raíz, no que usan la función modificada. Causa: el grafo indexa importaciones como edges, incluyendo `from modulo import *`. Solución: filtrar los resultados de `get_impact_radius` por `tipo: "call"` para obtener el blast radius real de llamadas directas, no el inflado por importaciones transitivas.
+- **Advertencia de alto impacto (N_total > 20) sin sugerir `/swl:checkpoint`**: el skill documenta que cuando N_total supera 20 se debe mostrar advertencia y sugerir checkpoint, pero el agente solo muestra el número sin la advertencia. Causa: omitir la condición `if N_total > 20` al construir el output del subcomando `impacto`. Solución: el bloque condicional de advertencia es parte del protocolo, no opcional — si N_total > 20, mostrar el aviso y sugerir checkpoint antes de continuar.
+- **`risk_score` del subcomando `cambios` calculado con grafo desactualizado**: el grafo fue construido hace 3 semanas y el codebase cambió significativamente. Causa: `graph.db` no se reconstruye automáticamente con cada commit. Solución: si la última actualización del grafo (verificar metadata) supera 7 días o hay más de 50 commits desde la última build, reconstruir el grafo antes de confiar en el risk score.

package/habilidades/tailwind-experto/SKILL.md

@@ -0,0 +1,240 @@
+---
+name: tailwind-experto
+description: Tailwind CSS v4 mejores prácticas. Cubre configuración CSS-first con @theme y @custom-variant, design tokens en Tailwind, patrones de componentes, responsive con breakpoints, dark mode, plugins custom, compilación JIT y anti-patrones como utility soup y @apply abuse.
+version: "1.0.0"
+herramientasPermitidas: [Read]
+exclusiones:
+  - "No cargar para CSS nativo moderno (Container Queries, @layer, Nesting, View Transitions) — para CSS nativo cargar `css-moderno`."
+  - "No cargar para accesibilidad (ARIA, contraste WCAG, navegación por teclado) — para accesibilidad cargar `accesibilidad-a11y`."
+  - "No cargar para Tailwind v3 con `tailwind.config.js` — la configuración CSS-first de v4 es incompatible con v3."
+  - "No cargar para CSS-in-JS (styled-components, Emotion) o Bootstrap/MUI — son ecosistemas distintos sin utilidades atómicas."
+evolvable: true  # default para skill estandar
+---
+# Tailwind CSS v4 Experto
+
+## Cuándo NO cargar
+
+- El trabajo es CSS nativo moderno: Container Queries, `@layer`, Nesting, View Transitions — cargar `css-moderno`.
+- El tema es accesibilidad: ARIA, contraste WCAG, focus trap, navegación por teclado — cargar `accesibilidad-a11y`.
+- El proyecto usa Tailwind v3 con `tailwind.config.js` — la configuración CSS-first con `@theme` es específica de v4 e incompatible con v3.
+- El proyecto usa CSS-in-JS, Bootstrap o Material UI sin Tailwind — son ecosistemas distintos.
+
+## Cambio Fundamental en v4
+
+Tailwind v4 abandona el archivo `tailwind.config.js` en favor de **configuración
+directa en CSS**. No más archivo de configuración JavaScript — todo se define
+con `@theme` y directivas CSS nativas.
+
+```css
+/* app/globals.css — la config ahora está aquí */
+@import "tailwindcss";
+
+@theme {
+  --font-sans: 'Inter', system-ui, sans-serif;
+  --font-mono: 'JetBrains Mono', monospace;
+
+  --color-primario: oklch(56% 0.2 250);
+  --color-primario-oscuro: oklch(46% 0.2 250);
+  --color-secundario: oklch(70% 0.15 160);
+
+  --radius-sm: 0.25rem;
+  --radius-md: 0.375rem;
+  --radius-lg: 0.5rem;
+  --radius-xl: 1rem;
+
+  --spacing-18: 4.5rem;
+  --spacing-88: 22rem;
+}
+```
+
+Para tokens de color completos, tipografía fluida y escalas, ver [recursos/referencia-completa.md](recursos/referencia-completa.md).
+
+---
+
+## @custom-variant
+
+Define variantes personalizadas sin plugin:
+
+```css
+/* Variante para elementos con data attribute */
+@custom-variant data-activo (&[data-activo='true']);
+@custom-variant data-disabled (&[data-disabled='true']);
+@custom-variant data-error (&[data-error='true']);
+
+/* Uso en HTML */
+/* <div data-activo="true" class="data-activo:bg-marca-100 data-activo:border-marca-500"> */
+```
+
+```css
+/* Variante para grupos custom */
+@custom-variant sidebar-collapsed (.sidebar-collapsed &);
+
+/* Uso */
+/* <nav class="w-64 sidebar-collapsed:w-16 transition-all"> */
+```
+
+---
+
+## Patrones de Componentes
+
+### Patrón: clases base + variantes (cva)
+
+```tsx
+// components/Button.tsx
+import { cva, type VariantProps } from 'class-variance-authority';
+
+const buttonVariants = cva(
+  // Clases base siempre presentes
+  'inline-flex items-center justify-center gap-2 rounded-md font-medium transition-colors focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-marca-500 disabled:pointer-events-none disabled:opacity-50',
+  {
+    variants: {
+      variante: {
+        primario: 'bg-marca-500 text-white hover:bg-marca-600 active:bg-marca-700',
+        secundario: 'bg-transparent border border-marca-500 text-marca-600 hover:bg-marca-50',
+        ghost: 'hover:bg-gray-100 text-gray-700',
+        destructivo: 'bg-error text-white hover:bg-red-700',
+      },
+      tamano: {
+        sm: 'h-8 px-3 text-sm',
+        md: 'h-10 px-4 text-base',
+        lg: 'h-12 px-6 text-lg',
+      },
+    },
+    defaultVariants: {
+      variante: 'primario',
+      tamano: 'md',
+    },
+  }
+);
+
+export function Button({ variante, tamano, className, ...props }: ButtonProps) {
+  return (
+    <button className={buttonVariants({ variante, tamano, className })} {...props} />
+  );
+}
+```
+
+Para patrones adicionales (layouts, tarjetas, plugins custom), ver [recursos/referencia-completa.md](recursos/referencia-completa.md).
+
+---
+
+## Responsive con Breakpoints
+
+### Sistema de breakpoints (v4 por defecto)
+
+| Prefijo | Ancho mínimo | Dispositivo típico |
+|---------|-------------|-------------------|
+| `sm:`   | 640px       | Móvil grande |
+| `md:`   | 768px       | Tablet |
+| `lg:`   | 1024px      | Laptop |
+| `xl:`   | 1280px      | Desktop |
+| `2xl:`  | 1536px      | Pantalla grande |
+
+### Mobile-first (siempre)
+
+```html
+<!-- Correcto: móvil base, desktop override -->
+<div class="grid grid-cols-1 md:grid-cols-2 lg:grid-cols-3 gap-4">
+
+<!-- MAL: desktop base, móvil override (requiere sobreescribir) -->
+<div class="grid grid-cols-3 max-md:grid-cols-1">
+```
+
+### Breakpoints personalizados en v4
+
+```css
+@theme {
+  --breakpoint-xs:  475px;
+  --breakpoint-3xl: 1920px;
+}
+```
+
+---
+
+## Dark Mode en v4
+
+```css
+/* globals.css */
+@import "tailwindcss";
+
+@theme {
+  --color-fondo: #ffffff;
+  --color-texto: #0f172a;
+}
+
+@media (prefers-color-scheme: dark) {
+  @theme {
+    --color-fondo: #0f172a;
+    --color-texto: #f1f5f9;
+  }
+}
+```
+
+```tsx
+// Dark mode con clase manual (toggle)
+<html className={tema === 'oscuro' ? 'dark' : ''}>
+
+// En el CSS
+@custom-variant dark (&:where(.dark, .dark *));
+```
+
+---
+
+## Anti-patrones
+
+### Utility Soup — demasiadas clases en un elemento
+
+```html
+<!-- MAL: ilegible, difícil de mantener -->
+<button class="inline-flex items-center justify-center gap-2 rounded-md bg-blue-600 px-4 py-2 text-sm font-medium text-white shadow-sm transition-colors hover:bg-blue-700 focus:outline-none focus:ring-2 focus:ring-blue-500 focus:ring-offset-2 active:bg-blue-800 disabled:cursor-not-allowed disabled:opacity-50">
+
+<!-- BIEN: extraer componente con cva() -->
+<Button variante="primario" tamano="sm">Guardar</Button>
+```
+
+### @apply Abuse — recrear Sass con Tailwind
+
+```css
+/* MAL: el propósito de @apply es crear un nuevo .scss, no reutilizar utilidades */
+.card {
+  @apply rounded-lg border border-gray-200 bg-white p-6 shadow-sm;
+}
+
+/* BIEN: si es reutilizable, hacer componente React/Vue/Angular */
+/* Si es un patrón CSS puro, usar custom property o @layer */
+@layer componentes {
+  .card {
+    border-radius: var(--radius-lg);
+    border: 1px solid var(--color-borde);
+    background: var(--color-superficie);
+    padding: var(--spacing-6);
+    box-shadow: var(--shadow-sm);
+  }
+}
+```
+
+### Clases condicionales con interpolación de string
+
+```tsx
+// MAL: Tailwind JIT no puede detectar clases dinámicas construidas con interpolación
+const color = 'azul';
+<div className={`bg-${color}-500`}> // 'bg-azul-500' no existe en el output
+
+// BIEN: objeto de mapeo completo
+const colorMap = {
+  azul:  'bg-blue-500',
+  rojo:  'bg-red-500',
+  verde: 'bg-green-500',
+} as const;
+<div className={colorMap[color]}>
+```
+
+## Gotchas / Errores comunes no obvios
+
+**En Tailwind v4, las variables de `@theme` no están disponibles en JavaScript**: a diferencia de v3 donde `tailwind.config.js` exporta los tokens directamente, en v4 los tokens son variables CSS (`--color-primario`) que solo viven en el CSS — no se pueden importar en componentes JavaScript para comparar valores programáticamente. Causa: el diseño CSS-first de v4 es intencional. Fix: para usar tokens en JavaScript (ej: en una librería de gráficas), leer las variables CSS en runtime con `getComputedStyle(document.documentElement).getPropertyValue('--color-primario')`.
+
+**`@apply` con clases que incluyen variantes responsivas (`md:flex`) lanza error en Tailwind v4**: `@apply md:flex` dentro de un bloque CSS no es válido porque las variantes responsivas en v4 son media queries generadas — no se pueden aplicar con `@apply`. Causa: `@apply` solo funciona con clases base, no con variantes de contexto como `md:`, `hover:` o `dark:`. Fix: escribir la media query CSS nativa directamente (`@media (min-width: theme(--breakpoint-md)) { display: flex; }`) o usar el patrón de componente con `cva()`.
+
+**La purga de clases de Tailwind v4 no detecta clases en archivos `.py`, `.rb` o templates de servidor no configurados**: si el backend genera HTML dinámicamente con strings de clases Tailwind, el compilador de v4 no las ve y las elimina del CSS final. Causa: la detección de contenido de v4 escanea archivos según la configuración de `content` — los templates de servidor no configurados están excluidos. Fix: agregar los paths de los templates al scanner de contenido en el `@import "tailwindcss"` con `source()` o en la config, o usar la directiva `@source` en el CSS.
+
+**`clsx` o `cn()` con objetos condicionales y clases que se superponen no garantiza el orden correcto**: `cn('p-4', condicion && 'p-8')` puede resultar en `p-4 p-8` en el HTML, y el navegador aplica la última clase declarada en el CSS — que es la que aparece último en la hoja de estilos de Tailwind, no la última en el string. Causa: la cascada CSS depende del orden de declaración en la hoja de estilos, no del orden en el atributo `class`. Fix: usar `twMerge` (o `cn` basado en `tailwind-merge`) que resuelve conflictos de clases del mismo grupo utilitario correctamente.