@saulwade/swl-ses 1.0.0

package/habilidades/ux-diseno/recursos/patrones-ux-referencia.md

@@ -0,0 +1,214 @@
+# UX Design — Patrones de Referencia Completos
+
+## Jerarquía Visual — Escala Tipográfica
+
+```css
+/* Escala tipográfica clara */
+:root {
+  --text-xs:   0.75rem;    /* 12px — metadatos, badges */
+  --text-sm:   0.875rem;   /* 14px — texto secundario */
+  --text-base: 1rem;       /* 16px — cuerpo */
+  --text-lg:   1.125rem;   /* 18px — subtítulos */
+  --text-xl:   1.25rem;    /* 20px — títulos de sección */
+  --text-2xl:  1.5rem;     /* 24px — títulos de página */
+  --text-3xl:  1.875rem;   /* 30px — hero / KPIs */
+
+  /* Pesos */
+  --font-normal:   400;
+  --font-medium:   500;
+  --font-semibold: 600;
+  --font-bold:     700;
+
+  /* Color como jerarquía */
+  --color-text-primary:   #111827;  /* Contenido principal */
+  --color-text-secondary: #6b7280;  /* Contenido de apoyo */
+  --color-text-disabled:  #9ca3af;  /* Deshabilitado */
+}
+```
+
+---
+
+## Estados de UI — Implementaciones Completas
+
+### Estado de Carga (Loading)
+
+```html
+<!-- Skeleton loader — mejor que spinner para listas -->
+<div class="skeleton-card" aria-busy="true" aria-label="Cargando expedientes...">
+  <div class="skeleton-line w-3/4 h-4 mb-2"></div>
+  <div class="skeleton-line w-1/2 h-3 mb-1"></div>
+  <div class="skeleton-line w-2/3 h-3"></div>
+</div>
+
+<!-- Spinner inline para acciones puntuales -->
+<button disabled>
+  <svg class="animate-spin h-4 w-4" viewBox="0 0 24 24" aria-hidden="true">...</svg>
+  Guardando...
+</button>
+```
+
+```css
+/* Skeleton con animación de shimmer */
+.skeleton-line {
+  background: linear-gradient(90deg, #f0f0f0 25%, #e0e0e0 50%, #f0f0f0 75%);
+  background-size: 200% 100%;
+  animation: shimmer 1.5s infinite;
+  border-radius: 4px;
+}
+
+@keyframes shimmer {
+  0% { background-position: -200% 0; }
+  100% { background-position: 200% 0; }
+}
+```
+
+### Estado Vacío (Empty State)
+
+```html
+<!-- BIEN: empty state con contexto y acción -->
+<div class="empty-state" role="status">
+  <img src="assets/empty-expedientes.svg" alt="" aria-hidden="true" />
+  <h3>No hay expedientes registrados</h3>
+  <p>Crea el primer expediente para comenzar a gestionar tu equipo.</p>
+  <a routerLink="/expedientes/nuevo" class="btn-primary">
+    Crear expediente
+  </a>
+</div>
+```
+
+### Estado de Error
+
+```html
+<!-- Error inline en formulario -->
+<div class="error-message" role="alert">
+  <svg class="error-icon" aria-hidden="true">...</svg>
+  <div>
+    <strong>No se pudo guardar el expediente</strong>
+    <p>El número de empleado ya existe en el sistema. Verifica el campo e intenta nuevamente.</p>
+  </div>
+  <button onclick="reintentar()">Reintentar</button>
+</div>
+
+<!-- Error de página completa (403, 404, 500) -->
+<div class="error-page">
+  <span class="error-code">404</span>
+  <h1>Página no encontrada</h1>
+  <p>La URL que buscas no existe o fue movida.</p>
+  <div class="acciones">
+    <a routerLink="/">Ir al inicio</a>
+    <button onclick="history.back()">Regresar</button>
+  </div>
+</div>
+```
+
+---
+
+## Micro-interacciones
+
+```css
+/* Feedback visual en acciones */
+
+/* Botón con confirmación visual de éxito */
+.btn-guardar.exito {
+  background-color: #16a34a;
+  transition: background-color 0.3s ease;
+}
+
+/* Hover suave en cards clicables */
+.card-empleado {
+  transition: transform 0.15s ease, box-shadow 0.15s ease;
+  cursor: pointer;
+}
+.card-empleado:hover {
+  transform: translateY(-2px);
+  box-shadow: 0 4px 12px rgba(0,0,0,0.1);
+}
+
+/* Animación de entrada para notificaciones */
+@keyframes slide-in {
+  from { transform: translateX(100%); opacity: 0; }
+  to   { transform: translateX(0);   opacity: 1; }
+}
+.toast {
+  animation: slide-in 0.25s ease-out;
+}
+
+/* Reducir movimiento para usuarios con vestibular disorders */
+@media (prefers-reduced-motion: reduce) {
+  *, *::before, *::after {
+    animation-duration: 0.01ms !important;
+    transition-duration: 0.01ms !important;
+  }
+}
+```
+
+---
+
+## Formularios — UX Específica
+
+```
+Orden de campos: del más familiar al más específico
+1. Nombre -> Apellido -> Email (todos conocen esto)
+2. Departamento -> Puesto (contexto)
+3. RFC -> CURP -> NSS (datos específicos de RRHH)
+
+Reglas de campo:
+- Label siempre visible (no solo placeholder)
+- Hint text debajo del campo, no encima
+- Error mensaje específico, no genérico
+- Marcar REQUERIDO con asterisco (*) y leyenda al inicio
+- Marcar OPCIONAL explícitamente (no asumir que el usuario lo sabe)
+- Autocompletar habilitado para datos personales (autocomplete="name", etc.)
+- Tab order lógico (de izquierda a derecha, arriba a abajo)
+- Formato de fecha en contexto mexicano: dd/mm/aaaa
+```
+
+---
+
+## Mobile First
+
+```css
+/* Base: mobile (320px+) */
+.grid-empleados {
+  display: grid;
+  grid-template-columns: 1fr;
+  gap: 16px;
+}
+
+/* Tablet (768px+) */
+@media (min-width: 768px) {
+  .grid-empleados {
+    grid-template-columns: repeat(2, 1fr);
+  }
+}
+
+/* Desktop (1024px+) */
+@media (min-width: 1024px) {
+  .grid-empleados {
+    grid-template-columns: repeat(3, 1fr);
+  }
+}
+
+/* Área táctil mínima en mobile */
+@media (pointer: coarse) {
+  button, a, input[type="checkbox"], input[type="radio"] {
+    min-height: 44px;
+    min-width: 44px;
+  }
+}
+```
+
+---
+
+## Anti-patrones UX Comunes
+
+| Anti-patrón | Efecto en usuario | Solución |
+|-------------|------------------|----------|
+| Dark pattern: pre-marcar checkboxes de suscripción | Suscripciones no deseadas | Checkboxes desmarcados por defecto |
+| Confirmar con "OK" y "Cancelar" sin contexto | Usuario hace clic en el incorrecto | "Eliminar expediente" y "Cancelar" |
+| Formulario pierde datos al navegar atrás | Frustración, trabajo perdido | Guardar borrador automáticamente |
+| Paginación sin indicar cuántos resultados hay | Usuario no sabe cuánto falta | "Mostrando 1-20 de 347 expedientes" |
+| Spinner que gira indefinidamente | Usuario no sabe si hay error | Timeout + mensaje de error |
+| Botón de submit duplicado | Doble envío de formulario | Deshabilitar tras primer clic |
+| Menú desplegable para 2-3 opciones | Fricción innecesaria | Radio buttons o tabs visibles |
+| Placeholder como label (desaparece al escribir) | Usuario olvida qué debe ir ahí | Label real + placeholder como ejemplo |

package/habilidades/validacion-ci-sistema/SKILL.md

@@ -0,0 +1,136 @@
+---
+name: validacion-ci-sistema
+description: Validación de integridad del sistema SWL inspirado en ECC CI stack. Cubre validación de frontmatter de agentes, validación de skills (SKILL.md presente y no vacío), validación de hooks (sintaxis Node.js, exit codes), validación de comandos, validación de reglas, catálogo automático con métricas y script ejecutable de validación.
+version: "1.0.0"
+herramientasPermitidas: [Read, Bash]
+exclusiones:
+  - "No cargar para validar el código de aplicación del usuario (tests, linting de Python/TS, cobertura) — este skill valida la integridad del sistema SWL (frontmatter de agentes, SKILL.md presentes, exit codes de hooks); para validación de código cargar `reglas/pruebas.md` o invocar `tdd-qa-swl`."
+  - "No cargar para diagnosticar por qué un agente específico falló en una tarea — este skill detecta problemas estructurales del sistema SWL, no bugs en la lógica de un agente; para diagnóstico de agente usar `evaluacion-agentes`."
+  - "No cargar si `/swl:salud` acaba de ejecutarse sin errores — la validación CI es un subconjunto de lo que salud corre; no tiene sentido duplicarla en la misma sesión."
+  - "No cargar para agregar un componente nuevo al sistema — primero crear el componente (agente, skill, hook) y luego ejecutar validación CI para verificarlo; no como guía de creación."
+evolvable: true  # default para skill estandar
+---
+# Validación e Integridad del Sistema SWL
+
+## Propósito
+
+El sistema SWL crece con el tiempo. Sin validación, acumula:
+- Agentes con frontmatter incompleto que no se pueden invocar
+- Skills sin SKILL.md que el loader ignora silenciosamente
+- Hooks que fallan con códigos de salida incorrectos
+- Comandos con formato inválido
+
+---
+
+## Reglas de Validación por Componente
+
+### Agentes
+
+- Campos OBLIGATORIOS: `name`, `description`
+- `description` mínimo 20 caracteres
+- `name` debe coincidir con nombre del archivo (kebab-case)
+- `model`, `permissionMode`, `color`: solo valores permitidos
+- `tools`: solo tools conocidas del sistema
+
+### Skills
+
+- `SKILL.md` DEBE existir y no estar vacío
+- Frontmatter YAML con `name` y `description` obligatorios
+- Mínimo 50 líneas de contenido
+
+### Hooks
+
+- Sintaxis Node.js válida (`node --check`)
+- SIEMPRE tener `process.exit()` explícito
+- Hooks de observación NUNCA usan `exit(1)` (bloquearía el flujo)
+- `execSync` SIEMPRE con `timeout`
+- Hooks Pre/PostToolUse DEBEN leer stdin
+
+### Comandos
+
+- Nombre en kebab-case estricto
+- Archivo `command.md`, `{nombre}.md` o `index.md` presente
+- Frontmatter YAML válido si existe
+- Contenido de instrucciones no vacío
+
+### Reglas
+
+- Sin reglas vacías o menores a 20 caracteres
+- Detección heurística de contradicciones SIEMPRE/NUNCA entre reglas
+
+---
+
+## Tabla de Exit Codes para Hooks
+
+| Tipo de Hook | Exit 0 | Exit 1 | Exit 2 |
+|-------------|--------|--------|--------|
+| Observación (Pre/PostToolUse) | Continuar | PROHIBIDO | PROHIBIDO |
+| Validación (PreToolUse bloqueante) | Permitir | Bloquear con mensaje | -- |
+| Notificación (Stop/SubagentStop) | OK | Ignorar | -- |
+
+---
+
+## Ejecución
+
+```bash
+# Validar todo el sistema
+node scripts/validar-sistema.js
+
+# Validar y generar catálogo
+node scripts/validar-sistema.js --catalog
+
+# En CI
+npm run validate:ci
+```
+
+El script ejecutable está en `scripts/validar-sistema.sh`.
+
+### package.json scripts
+
+```json
+{
+  "scripts": {
+    "validate":         "node scripts/validar-sistema.js",
+    "validate:catalog": "node scripts/validar-sistema.js --catalog",
+    "validate:ci":      "node scripts/validar-sistema.js && echo 'Sistema íntegro'"
+  }
+}
+```
+
+---
+
+## Anti-patrones
+
+- Agentes sin `name` y `description` (el loader los ignora)
+- Hooks con `process.exit(1)` en observaciones (bloquean el agente)
+- Skills con SKILL.md vacío o sin frontmatter
+- No ejecutar validación antes de commit
+- Ignorar advertencias acumuladas
+- Comandos en snake_case o camelCase
+
+---
+
+## Checklist
+
+- [ ] `npm run validate` pasa sin errores
+- [ ] Todos los agentes tienen `name` + `description`
+- [ ] Todos los skills tienen `SKILL.md` con frontmatter
+- [ ] Hooks tienen `process.exit()` explícito
+- [ ] Hooks de observación no usan `exit(1)`
+- [ ] Comandos en kebab-case
+
+Para código fuente completo de todos los validadores (agentes, skills, hooks, comandos, reglas, catálogo), ver [recursos/validadores-completos.md](recursos/validadores-completos.md).
+
+## Cuándo NO cargar
+
+- Se valida código de aplicación del usuario (tests Python/TS, cobertura, linting) — este skill valida la integridad del sistema SWL; para código de aplicación cargar `reglas/pruebas.md` o invocar `tdd-qa-swl`.
+- `/swl:salud` acaba de ejecutarse sin errores en esta sesión — la validación CI es un subconjunto de lo que salud ejecuta; duplicarla no aporta información nueva.
+- El objetivo es diagnosticar por qué un agente específico falló en su tarea de dominio — este skill detecta problemas estructurales (frontmatter faltante, exit code incorrecto), no bugs en la lógica de un agente; para eso usar `evaluacion-agentes`.
+- Se está creando un componente nuevo y se necesita orientación sobre la estructura — este skill verifica componentes existentes, no guía la creación; usar `estructura-proyecto-claude` para crear con la estructura correcta desde el inicio.
+
+## Gotchas / Errores comunes no obvios
+
+- **Hook de observabilidad que usa `process.exit(1)` detectado como error crítico**: el validador marca el hook como inválido pero el hook fue escrito intencionalmente para bloquear en ciertos escenarios. Causa: el validador distingue entre hooks de observación (deben usar `exit(0)` siempre) y hooks de bloqueo (pueden usar `exit(1)` para rechazar acciones); si el hook no está categorizado correctamente, el validador aplica la regla incorrecta. Solución: verificar si el hook es bloqueante o de observación antes de corregir — un guardrail de seguridad que usa `exit(1)` es correcto; un hook de telemetría que usa `exit(1)` es un bug.
+- **Agente con `name` diferente al nombre de archivo pasa validación en local pero falla en CI**: el validador local compara el campo `name` del frontmatter con el nombre del directorio, pero CI usa la ruta del archivo. Causa: un agente renombrado actualiza el directorio pero no el campo `name` en el frontmatter. Solución: el checklist dice "name debe coincidir con nombre del archivo (kebab-case)" — al renombrar un agente o skill, actualizar el campo `name` del frontmatter en el mismo commit.
+- **`npm run validate` pasa sin advertencias pero `/swl:salud` reporta inconsistencias**: el script de validación CI cubre un subconjunto de las verificaciones de salud. Causa: las validaciones de grafo de dependencias, métricas de evolución y consistencia de versiones solo corren en `/swl:salud`, no en el validador CI básico. Solución: antes de un release o merge importante, ejecutar `/swl:salud` completo, no solo la validación CI — la validación CI es el mínimo para commits diarios.
+- **Skills con `description: >` YAML multiline registrados como sin frontmatter**: el validador usa una regex basada solo en LF (`/^---\n[\s\S]*?\n---/`) que no parsea correctamente archivos con terminaciones CRLF. Causa: archivos creados en Windows con CRLF en el frontmatter. Solución: si el validador reporta `sin-frontmatter` en un skill que claramente tiene frontmatter, verificar las terminaciones de línea con `file skill.md` — convertir CRLF→LF con `git config core.autocrlf input` o `sed -i 's/\r//'`.