@saulwade/swl-ses 1.0.0

package/habilidades/wiki-conocimiento/SKILL.md

@@ -0,0 +1,276 @@
+---
+name: wiki-conocimiento
+description: >
+  Gestión de conocimiento del proyecto con grafo de conocimiento y búsqueda semántica.
+  Integra patrones de LightRAG (grafo + vectores) para indexar aprendizajes, ADRs,
+  sesiones y documentación del proyecto. Cargar cuando se use /swl:wiki o se necesite
+  recuperar conocimiento acumulado del proyecto de forma semántica.
+version: "1.0.0"
+herramientasPermitidas: [Read, Glob, Grep]
+user-invocable: false
+exclusiones:
+  - "No cargar para búsqueda simple de aprendizajes o sesiones anteriores — `memoria-busqueda` cubre esa necesidad con 3 capas de progressive disclosure a menor costo; este skill añade el grafo de conocimiento semántico que solo compensa para consultas relacionales complejas."
+  - "No cargar si el proyecto tiene menos de 20 entradas en APRENDIZAJES.md o menos de 10 sesiones — el grafo de conocimiento no tiene suficiente masa crítica para ser útil con tan pocos datos; usar `memoria-busqueda` directamente."
+  - "No cargar para indexar o buscar en código fuente del codebase — el grafo indexa decisiones, aprendizajes, ADRs y sesiones, no código; para búsqueda en código usar Grep o `swl-revisar-impacto`."
+  - "No cargar para persistir aprendizajes nuevos de la sesión — eso es `extractor-de-aprendizajes`; este skill lee y consulta el grafo existente, no lo actualiza directamente."
+evolvable: true  # default para skill estandar
+---
+# Wiki de Conocimiento del Proyecto
+
+Sistema de gestión de conocimiento que combina grafo de conocimiento con búsqueda
+semántica para recuperar información acumulada del proyecto.
+
+## Cuándo cargar
+
+- `/swl:wiki query "..."` necesita buscar conocimiento del proyecto
+- Un agente SWL necesita contexto de decisiones previas antes de implementar
+- Se quiere indexar nuevos aprendizajes o ADRs
+- Se necesita trazar relaciones entre decisiones, bugs y soluciones
+
+## Arquitectura de referencia
+
+```
+Fuentes de conocimiento:
+  .planning/APRENDIZAJES.md    → Aprendizajes curados
+  .planning/adrs/              → Decisiones de arquitectura (ADRs)
+  .planning/sessions/          → Historial de sesiones
+  .planning/COMPACTACION.md    → Contexto compactado
+  docs/                        → Documentación del proyecto
+
+     ↓ Ingestión
+
+  Chunking → Extracción de entidades/relaciones → Grafo de conocimiento
+                                                        ↓
+                                          Embeddings → Vector store
+                                                        ↓
+  Consulta → Keyword extraction → Retrieval híbrido → Respuesta contextual
+```
+
+## Modos de búsqueda (patrón LightRAG)
+
+Basado en los 5 modos de retrieval de LightRAG:
+
+### 1. Local — Preguntas específicas
+- Extrae keywords de bajo nivel de la consulta
+- Recupera entidades cercanas en el grafo
+- Sigue relaciones para contexto adicional
+- **Usar para:** "¿Qué decidimos sobre el manejo de errores en el módulo de pagos?"
+
+### 2. Global — Preguntas amplias
+- Extrae keywords de alto nivel
+- Recupera relaciones agregadas y resúmenes de comunidades
+- **Usar para:** "¿Cuáles son los patrones arquitectónicos principales del proyecto?"
+
+### 3. Híbrido — Combina local + global
+- Ejecuta ambas estrategias y fusiona resultados
+- **Usar para:** Preguntas que necesitan tanto detalle como panorama general
+
+### 4. Naive — Búsqueda directa por similaridad
+- Sin grafo, solo embeddings de chunks
+- Más rápido pero menos contexto
+- **Usar para:** Búsquedas rápidas cuando se conoce el texto aproximado
+
+### 5. Mix — Recomendado (grafo + vectores)
+- Combina knowledge graph + chunk embeddings
+- Con reranking adaptativo
+- **Default para /swl:wiki query**
+
+## Modelo de entidades
+
+### Ontología tipada (patrón Zep)
+
+Define tipos de entidades y relaciones válidas entre ellas.
+Una ontología formal previene incoherencias en el grafo.
+
+### Tipos de entidades en el grafo
+| Tipo | Descripción | Fuente típica |
+|------|-------------|---------------|
+| `Decisión` | Decisión arquitectónica o técnica | ADRs, COMPACTACION.md |
+| `Patrón` | Patrón de diseño adoptado | APRENDIZAJES.md |
+| `AntiPatrón` | Práctica a evitar | APRENDIZAJES.md |
+| `Componente` | Módulo, servicio o librería | Código fuente |
+| `Bug` | Bug conocido y su solución | Sessions, APRENDIZAJES.md |
+| `Tecnología` | Framework, librería o herramienta | package.json, pyproject.toml |
+| `Persona` | Desarrollador o stakeholder | Git blame, sessions |
+| `Requisito` | Requisito funcional o no-funcional | PRD, ADRs |
+| `Preferencia` | Preferencia técnica del usuario/equipo | Feedback, sessions |
+| `Evento` | Incidente, release, migración | Historial, COMPACTACION.md |
+
+### Combinaciones válidas de relaciones (ontología)
+
+| Relación | Source válido | Target válido |
+|----------|-------------|---------------|
+| `causado_por` | Bug | Patrón, AntiPatrón, Componente |
+| `resuelto_con` | Bug | Decisión, Patrón |
+| `depende_de` | Componente | Componente, Tecnología |
+| `reemplaza` | Patrón, Decisión | AntiPatrón, Decisión |
+| `usa` | Componente | Tecnología |
+| `decidido_en` | Decisión | Evento |
+| `confirmado_por` | Patrón, Decisión | Evento |
+| `prefiere` | Persona | Tecnología, Patrón, Preferencia |
+| `requiere` | Requisito | Componente, Tecnología |
+
+### Grafo temporal (patrón Zep)
+
+Cada entidad y relación tiene timestamps de vigencia:
+
+```
+{
+  "id": "decision-001",
+  "tipo": "Decisión",
+  "nombre": "Usar SQLAlchemy async en FastAPI",
+  "valid_at": "2026-04-10",     // Cuándo empezó a ser válido
+  "invalid_at": null,           // null = vigente actualmente
+  "created_at": "2026-04-10",   // Cuándo se registró
+  "fuente": "sesión-2026-04-10"
+}
+```
+
+**Reglas de vigencia:**
+- `valid_at` obligatorio en toda entidad/relación
+- `invalid_at = null` → entidad vigente (incluir en consultas normales)
+- `invalid_at = fecha` → entidad obsoleta (excluir de consultas, incluir en historial)
+- Al crear una entidad que contradice otra → marcar la anterior con `invalid_at` = hoy
+- Nunca borrar entidades obsoletas — solo marcar como inválidas para trazabilidad
+
+### Clasificación de hechos por impacto (fact rating, patrón Zep)
+
+Cada hecho extraído se clasifica automáticamente por impacto:
+
+| Rating | Criterio | Ejemplo |
+|--------|----------|---------|
+| **HIGH** | Decisión arquitectónica irreversible, bug crítico, cambio de patrón | "Se migró de REST a GraphQL por requisitos de rendimiento" |
+| **MEDIUM** | Preferencia técnica, gotcha documentado, patrón confirmado | "SQLAlchemy async requiere selectinload() obligatorio" |
+| **LOW** | Información contextual, observación menor | "El build tarda 3 minutos en promedio" |
+
+**Mapeo a modelo 4-tier de swl-ses:**
+- HIGH → Tipo A (verdad estructural)
+- MEDIUM → Tipo B (gotcha/anti-patrón operativo)
+- LOW → Tipo C (preferencia/configuración)
+
+### Tipos de relaciones
+| Relación | Ejemplo |
+|----------|---------|
+| `causado_por` | Bug X fue causado_por Patrón Y |
+| `resuelto_con` | Bug X fue resuelto_con Decisión Z |
+| `depende_de` | Componente A depende_de Componente B |
+| `reemplaza` | Patrón X reemplaza AntiPatrón Y |
+| `usa` | Componente A usa Tecnología B |
+| `decidido_en` | Decisión X decidido_en ADR-001 |
+| `confirmado_por` | Patrón X confirmado_por sesión 2026-04-10 |
+
+## Patrón Compiled Truth (v5.6.0)
+
+Cada entidad del grafo sigue el patrón Compiled Truth:
+
+```markdown
+## [Nombre de la entidad]
+
+### Compiled Truth (síntesis curada)
+- Resumen en 2-3 oraciones
+- Estado actual: vigente/obsoleto/en_revisión
+
+### Timeline (evidencia cronológica)
+- [2026-04-01] [F:APRENDIZAJES] — Primera mención
+- [2026-04-10] [F:sesión] — Confirmado en implementación
+- [2026-04-12] [F:ADR-005] — Formalizado como decisión
+```
+
+## Integración con LightRAG
+
+### Implementación recomendada (servicio auxiliar)
+
+```python
+# scripts/lightrag-wiki.py — Servicio local de conocimiento del proyecto
+from lightrag import LightRAG, QueryParam
+
+async def inicializar_wiki(directorio_proyecto: str) -> LightRAG:
+    """Inicializa LightRAG con almacenamiento local para el proyecto."""
+    rag = LightRAG(
+        working_dir=f"{directorio_proyecto}/.planning/wiki-index",
+        llm_model_func=llm_completar,      # Wrapper para Claude
+        embedding_func=embedding_generar,   # Wrapper para embeddings
+        chunk_token_size=1200,
+        chunk_overlap_token_size=100,
+        enable_llm_cache=True,              # Caché para operaciones repetitivas
+    )
+    await rag.initialize_storages()
+    return rag
+
+async def indexar_fuentes(rag: LightRAG, directorio_proyecto: str):
+    """Indexa todas las fuentes de conocimiento del proyecto."""
+    fuentes = [
+        f"{directorio_proyecto}/.planning/APRENDIZAJES.md",
+        f"{directorio_proyecto}/.planning/COMPACTACION.md",
+    ]
+    # Agregar ADRs si existen
+    import glob
+    fuentes += glob.glob(f"{directorio_proyecto}/.planning/adrs/*.md")
+    # Agregar sesiones recientes (últimas 10)
+    sesiones = sorted(glob.glob(f"{directorio_proyecto}/.planning/sessions/*.md"))[-10:]
+    fuentes += sesiones
+
+    for fuente in fuentes:
+        with open(fuente, 'r', encoding='utf-8') as f:
+            contenido = f.read()
+        await rag.ainsert(contenido, file_paths=[fuente])
+
+async def consultar(rag: LightRAG, pregunta: str, modo: str = "mix") -> str:
+    """Consulta el grafo de conocimiento del proyecto."""
+    resultado = await rag.aquery(
+        pregunta,
+        param=QueryParam(
+            mode=modo,
+            top_k=20,
+            chunk_top_k=10,
+            max_total_tokens=15000,
+            enable_rerank=True,
+        ),
+    )
+    return resultado.response
+```
+
+### Flujo de actualización incremental
+
+```
+1. /swl:aprender extrae aprendizajes → guarda en APRENDIZAJES.md
+2. Hook post-aprender indexa nuevo contenido en LightRAG
+3. Próxima consulta /swl:wiki incluye aprendizajes recientes
+4. Consolidación periódica: re-indexar todo para mantener coherencia del grafo
+```
+
+## Implementación actual (sin LightRAG — búsqueda textual)
+
+Mientras LightRAG no esté instalado, `/swl:wiki query` usa:
+
+1. `session-fts.js` (BM25) para búsqueda en sesiones
+2. `memory-search.js` (TF-IDF) para búsqueda en memoria
+3. Grep directo en `.planning/` para ADRs y aprendizajes
+
+La migración a LightRAG es incremental: agregar el servicio como MCP server
+sin romper la funcionalidad existente.
+
+## Evaluación de calidad (patrón RAGAS)
+
+Para evaluar la calidad de las respuestas del wiki:
+
+| Métrica | Descripción | Umbral aceptable |
+|---------|-------------|-------------------|
+| Faithfulness | ¿La respuesta se basa en las fuentes recuperadas? | ≥ 0.85 |
+| Answer relevancy | ¿La respuesta es relevante a la pregunta? | ≥ 0.80 |
+| Context precision | ¿Los chunks recuperados son precisos? | ≥ 0.75 |
+| Context recall | ¿Se recuperaron todos los chunks relevantes? | ≥ 0.70 |
+
+## Cuándo NO cargar
+
+- La búsqueda es sobre aprendizajes o sesiones anteriores con una query de texto directa — `memoria-busqueda` tiene 3 capas de progressive disclosure y cuesta menos; el grafo de wiki compensa solo cuando la consulta requiere traversal de relaciones entre entidades.
+- El proyecto tiene menos de 20 entradas en APRENDIZAJES.md y menos de 10 sesiones — sin masa crítica de datos, el grafo no tiene suficientes nodos para que las relaciones aporten valor sobre una búsqueda textual simple.
+- Se busca en código fuente (funciones, patrones, implementaciones) — el grafo indexa decisiones, aprendizajes y ADRs, no código; para búsqueda de código usar Grep directamente o `swl-revisar-impacto` para análisis estructural.
+- El objetivo es registrar un aprendizaje nuevo de la sesión actual — eso es `extractor-de-aprendizajes`; este skill lee el grafo existente, no persiste nuevo conocimiento directamente.
+
+## Gotchas / Errores comunes no obvios
+
+- **Entidades con `invalid_at` no excluidas de consultas normales**: el wiki devuelve decisiones obsoletas como vigentes porque la query no filtra por `invalid_at = null`. Causa: LightRAG indexa el contenido textual de los documentos pero no ejecuta filtros por campo del grafo automáticamente. Solución: al consultar decisiones vigentes, agregar `invalid_at = null` como filtro en la capa de post-procesamiento del resultado — o en el modo de implementación sin LightRAG, verificar el campo en el JSON antes de incluir la entidad.
+- **Indexación masiva con `rag.ainsert()` llamado para cada archivo en un loop sin batching**: el proceso de ingestión tarda 45 minutos en indexar 50 sesiones porque cada llamada espera la finalización de la anterior. Causa: `ainsert()` es async pero se llama con `await` secuencial en lugar de `asyncio.gather()`. Solución: usar `asyncio.gather(*[rag.ainsert(c) for c in contenidos])` para indexar en paralelo — LightRAG soporta ingestión concurrente.
+- **Consulta en modo `global` devuelve respuesta genérica sin usar datos del proyecto**: el agente usa modo `mix` pero el grafo no tiene suficientes entidades indexadas para el reasoning global. Causa: el modo `global` de LightRAG requiere suficiente masa de entidades para hacer inferencias; con pocos documentos, el modo `local` o `naive` da mejores resultados. Solución: para proyectos pequeños usar modo `local` (top_k sobre chunks cercanos); reservar modo `global` o `mix` para proyectos con 50+ fuentes indexadas.
+- **`valid_at` ausente en entidades del grafo generadas automáticamente**: las entidades creadas por el extractor de hechos de LightRAG no incluyen el timestamp de vigencia requerido por el patrón Compiled Truth. Causa: LightRAG extrae entidades con sus propios campos; el schema de vigencia de swl-ses es una extensión custom que el extractor base no conoce. Solución: agregar un paso de enriquecimiento post-extracción que inyecte `valid_at = hoy` y `invalid_at = null` en cada entidad nueva antes de almacenarla.

package/habilidades/wireframes-flujos/SKILL.md

@@ -0,0 +1,212 @@
+---
+name: wireframes-flujos
+description: Wireframes y user flows para Claude. Cubre wireframes descriptivos en formato texto, user flows como diagrama de texto, information architecture, navigation patterns (tabs/drawers/breadcrumbs), empty states/error states/loading states, decisiones de breakpoints responsivos y protocolo de handoff a implementador.
+version: "1.0.0"
+herramientasPermitidas: [Read, Grep]
+evolvable: true  # default para skill estandar
+exclusiones:
+  - "No cargar para diseño visual de alta fidelidad con colores, tipografía y design tokens — para diseño visual de UI cargar `design-tokens` y el skill de diseño responsivo."
+  - "No cargar para implementar los componentes Angular/React descritos en el wireframe — los wireframes son specs para el implementador; para implementación cargar `angular-moderno` o el skill de frontend correspondiente."
+  - "No cargar para investigación de usuarios (entrevistas, encuestas, usabilidad) — los wireframes asumen que el UX research ya definió las necesidades; para investigación cargar el skill de UX correspondiente."
+  - "No cargar para generación de diagramas UML de arquitectura o diagramas de secuencia técnicos — para diagramas de arquitectura cargar `diagrama-arquitectura` o `generacion-mermaid`."
+---
+# Wireframes y Flujos de Usuario
+
+## Cuándo NO cargar
+
+- La tarea es diseño visual de alta fidelidad (colores, tipografía, design tokens): cargar `design-tokens`.
+- La tarea es implementar los componentes descritos en el wireframe: cargar `angular-moderno` o el skill de frontend del stack.
+- La tarea es investigación de usuarios (entrevistas, usabilidad): cargar el skill de UX correspondiente.
+- La tarea es diagramas de arquitectura o secuencia técnicos: cargar `diagrama-arquitectura` o `generacion-mermaid`.
+
+## Filosofía
+
+Claude trabaja con **wireframes descriptivos en texto**, no imágenes. Un wireframe
+de texto bien escrito comunica estructura, jerarquía, comportamiento y decisiones
+de UX mejor que un mockup visual de baja fidelidad, y puede ser consumido
+directamente por el agente implementador sin ambigüedad.
+
+El objetivo no es describir cómo se verá — es describir qué hay, dónde está,
+qué hace y cómo responde al usuario.
+
+---
+
+## 1. Formato de Wireframe Descriptivo
+
+### Estructura de un wireframe de pantalla
+
+```
+PANTALLA: [Nombre de la Pantalla]
+URL/RUTA: [/ruta o nombre de pantalla]
+PROPÓSITO: [Qué logra el usuario aquí en 1 oración]
+USUARIO: [Rol o tipo de usuario que ve esta pantalla]
+
+━━━ LAYOUT ━━━
+[Descripción del grid/layout general]
+
+┌─────────────────────────────────────────────┐
+│  HEADER                                     │
+│  [Logo]    [Nav: Inicio | Usuarios | Config]│
+│                          [Avatar + Dropdown]│
+├──────────────────────────────────────────── ┤
+│  SIDEBAR (240px fijo)  │  CONTENIDO PRINCIPAL│
+│                        │                     │
+│  - Sección A (activa)  │  [Área de trabajo]  │
+│  - Sección B           │                     │
+│  - Sección C           │                     │
+├────────────────────────┴─────────────────────┤
+│  FOOTER: versión | soporte | términos        │
+└──────────────────────────────────────────────┘
+
+━━━ CONTENIDO PRINCIPAL (detalle) ━━━
+
+H1: "Gestión de Usuarios"
+[Botón primario: "+ Nuevo Usuario"] [Botón secundario: "Exportar CSV"]
+
+Barra de búsqueda: [Buscar por nombre o email...] [Filtros]
+
+Tabla:
+  Columnas: Nombre | Email | Rol | Último acceso | Acciones
+  Ordenable por: Nombre (asc actual), Último acceso
+  Filas: 20 por página
+  Acciones por fila: [Editar] [Desactivar] [...]
+
+Paginación: [< Anterior] [1] [2] [3] [...] [12] [Siguiente >]
+
+━━━ COMPORTAMIENTOS ━━━
+- Búsqueda: debounce 300ms, actualiza tabla en tiempo real
+- Click en fila: abre panel lateral con detalle del usuario
+- Nuevo Usuario: abre modal de 3 pasos
+- Filtros: se persisten en query params de la URL
+
+━━━ ESTADOS ━━━
+(Ver sección de estados abajo)
+```
+
+---
+
+## 2. User Flows (Diagrama en Texto)
+
+### Notación de flujo
+
+```
+[Pantalla] → acción → [Pantalla destino]
+[Pantalla] → acción → (Decisión) → SÍ → [A]
+                                 → NO → [B]
+[Pantalla] → acción → {API call} → éxito → [C]
+                                 → error → [D]
+```
+
+### Ejemplo: Flujo de Login
+
+```
+[Login]
+  Ingresa email y password
+  │
+  ├─ [Olvidé mi contraseña] → [Recuperar Contraseña]
+  │                              ↓
+  │                           {API: reset}
+  │                              ├─ éxito → [Mensaje: "Revisa tu email"]
+  │                              └─ error → [Error inline: "Email no registrado"]
+  │
+  └─ [Iniciar Sesión]
+       ▼
+    {API: login}
+       ├─ éxito, rol=ADMIN → [Dashboard Admin]
+       ├─ éxito, rol=USUARIO → [Dashboard Usuario]
+       ├─ error: credenciales → Error inline (sin indicar cuál es incorrecto)
+       ├─ error: cuenta bloqueada → Modal: "Cuenta bloqueada"
+       └─ error: 2FA requerido → [Verificación 2FA]
+```
+
+Para flujos multi-paso completos, mapa de sitio IA y navigation patterns detallados,
+ver [recursos/referencia-completa.md](recursos/referencia-completa.md).
+
+---
+
+## 3. Empty States, Error States, Loading States
+
+### Empty State
+
+```
+CUANDO: La lista/tabla no tiene datos
+
+ESTRUCTURA:
+[Ícono ilustrativo grande]
+[Título: "No hay usuarios aún"]
+[Descripción: "Agrega el primer usuario para comenzar."]
+[Botón primario: "+ Agregar Usuario"]   ← solo si el usuario tiene permiso
+
+VARIANTES:
+- Primera vez (onboarding): ícono friendly, CTA activo
+- Sin resultados de búsqueda: "Intenta con otros filtros", [Limpiar filtros]
+- Sin permisos: ícono de candado, sin CTA
+```
+
+### Error States
+
+```
+Error inline (campos de formulario):
+[Input con borde rojo]
+"El email ya está registrado"   ← debajo del campo, 14px, color error
+
+Error de página (4xx):
+H1: "Página no encontrada" (404) | "Acceso denegado" (403)
+[Descripción en lenguaje humano, sin códigos de error]
+[Botón: "Ir al inicio"]
+
+Error de API (500 en acción):
+Toast (rojo): "No se pudo guardar. Intenta de nuevo."
+[Reintentar]   ← si la acción es reintentable
+NO mostrar el error técnico al usuario
+```
+
+### Loading States
+
+```
+SKELETON (preferido para listas y cards — evita layout shift):
+┌─────────────────────────┐
+│ ████████████ ██████████ │  ← líneas grises animadas
+│ ████████             ██ │
+└─────────────────────────┘
+
+SPINNER (para acciones puntuales — submit de form, botón):
+[Botón: Guardando...]   ← botón deshabilitado con spinner inline
+
+PROGRESO (para operaciones largas >3s):
+Subiendo archivo: [████████░░░░░░░] 53%
+[Cancelar]
+```
+
+---
+
+## 4. Handoff de Wireframe a Implementador
+
+El wireframe está listo para el implementador cuando incluye:
+
+- Nombre, ruta URL y propósito de cada pantalla
+- Layout descrito con grid, columnas y proporciones
+- Todos los elementos nombrados específicamente
+- Comportamientos interactivos descritos (hover, click, debounce)
+- Empty, loading y error states definidos
+- Entradas y salidas de la pantalla
+- API calls marcadas con `{API: ...}` y manejo de errores
+- Comportamiento responsive en desktop, tablet y móvil
+
+El implementador NO debe inventar comportamientos no descritos en el wireframe.
+Si encuentra una ambigüedad, PARA y reporta. No adivina.
+
+Para checklist de entrega completo y decisiones de breakpoints responsive,
+ver [recursos/referencia-completa.md](recursos/referencia-completa.md).
+
+---
+
+## Gotchas / Errores comunes no obvios
+
+**Los wireframes de texto no especifican el comportamiento de scroll en paneles laterales, causando que el implementador elija entre `overflow-y: auto` en el sidebar o en el body, y la decisión incorrecta hace que el header desaparezca al scrollear**: en un layout con sidebar fijo y contenido principal scrollable, si el wireframe dice "SIDEBAR (240px fijo)" sin especificar `height: 100vh; overflow-y: auto` explícitamente, el implementador puede implementar el scroll en el `body` haciendo que el sidebar desaparezca del viewport. Causa: las dimensiones en wireframes de texto no implican comportamiento de overflow ni posicionamiento CSS. Fix: en la sección `━━━ LAYOUT ━━━`, agregar siempre la línea `SCROLL: [componente que scrollea] — [contenido fijo que no scrollea]`. Ejemplo: "SCROLL: contenido principal. FIJO: header y sidebar".
+
+**Un user flow que muestra `{API: login} → éxito, rol=ADMIN → [Dashboard Admin]` no especifica qué pasa durante la transición — si hay un estado de carga, un redirect, o si el componente de Dashboard es el mismo con diferente contenido**: el implementador que lee el flujo puede implementar un redirect `/dashboard-admin` (ruta separada) o un router Angular que carga el componente `DashboardComponent` con un guard, o simplemente mostrar/ocultar secciones en el mismo componente. Las tres implementaciones son válidas según el flujo, pero incompatibles entre sí. Causa: los user flows de texto documentan estados y transiciones pero no el mecanismo técnico de navegación. Fix: agregar una nota de "decisión de implementación" en cada `{API call} → éxito → [pantalla]` donde la transición no sea obvia: `[Dashboard Admin] ← guard verifica rol en el token, ruta separada /admin/dashboard` o `[Dashboard compartido, contenido condicional por rol]`.
+
+**Los wireframes de empty states que incluyen `[Botón primario: "+ Agregar"]` sin especificar las condiciones de visibilidad del botón resultan en interfaces donde usuarios sin permiso de escritura ven un botón que falla con 403 al hacer clic**: el wireframe describe el empty state feliz, pero el implementador que ve `[Botón primario: "+ Agregar Usuario"]` no sabe si debe verificar el permiso antes de renderizarlo. Causa: los wireframes frecuentemente documentan el flujo del usuario con permisos completos y omiten los estados de permisos reducidos. Fix: en la sección `COMPORTAMIENTOS` de cada pantalla, incluir explícitamente las condiciones de visibilidad de acciones: `"+ Agregar Usuario: visible solo si usuario tiene permiso USERS_WRITE"`. Si la pantalla tiene variantes por rol, documentar cada variante como sección separada `━━━ VARIANTE: USUARIO_SOLO_LECTURA ━━━`.
+
+**Los wireframes de formularios multi-paso no especifican si el estado de los pasos anteriores persiste cuando el usuario regresa al paso 1 desde el paso 3, causando inconsistencias entre implementaciones donde uno limpia el form y otro lo conserva**: en un wizard de 3 pasos donde el paso 2 depende de datos del paso 1, si el usuario regresa al paso 1 y cambia el tipo de cuenta, el paso 2 puede quedar con datos inválidos para el nuevo tipo. Causa: los user flows documentan la ruta feliz forward; la navegación hacia atrás y sus efectos en el estado son una decisión de UX no documentada. Fix: en el user flow del wizard, agregar explícitamente los bordes de retroceso: `[Paso 2] → [Atrás] → [Paso 1, datos anteriores pre-llenados]` o `[Paso 1, formulario limpio, pasos 2 y 3 invalidados]`. La elección entre ambos depende del impacto de un cambio en paso 1 sobre los datos de pasos posteriores.

package/habilidades/wireframes-flujos/recursos/referencia-completa.md

@@ -0,0 +1,192 @@
+# Referencia Completa — Wireframes y Flujos de Usuario
+
+## Ejemplo: Flujo de Crear Usuario (multi-paso)
+
+```
+[Lista Usuarios]
+  → Click "+ Nuevo Usuario"
+  → [Modal: Paso 1/3 — Datos Básicos]
+      Campos: Nombre, Email, Teléfono (opcional)
+      [Cancelar] [Siguiente →]
+          │
+          └─ Validación front
+               ├─ falla → Errores inline, permanecer en Paso 1
+               └─ ok → [Modal: Paso 2/3 — Rol y Permisos]
+                           Selector: Rol (Admin/Usuario/Moderador)
+                           Checkboxes de permisos granulares
+                           [← Anterior] [Siguiente →]
+                               │
+                               └─ ok → [Modal: Paso 3/3 — Confirmar]
+                                           Resumen de datos a crear
+                                           [← Anterior] [Crear Usuario]
+                                               │
+                                               ▼
+                                            {API: POST /usuarios}
+                                               │
+                                               ├─ 201 Created
+                                               │    → Cerrar modal
+                                               │    → Toast: "Usuario creado exitosamente"
+                                               │    → Actualizar tabla (invalidar caché)
+                                               │
+                                               └─ 409 Conflict (email duplicado)
+                                                    → Volver a Paso 1
+                                                    → Error en campo email
+```
+
+---
+
+## Information Architecture — Mapa de Sitio
+
+```
+APP SIGAF
+├── Auth (sin sidebar)
+│   ├── /login
+│   ├── /recuperar-contrasena
+│   └── /reset-contrasena/:token
+│
+├── Dashboard /               (todos los roles)
+│
+├── Usuarios /usuarios        (ADMIN, AUDITOR)
+│   ├── Lista /usuarios
+│   ├── Detalle /usuarios/:id
+│   └── Crear  /usuarios/nuevo
+│
+├── Reportes /reportes        (todos los roles, datos filtrados por rol)
+│   ├── Resumen /reportes
+│   ├── Por período /reportes/periodo
+│   └── Exportar  /reportes/exportar
+│
+└── Configuración /config     (solo ADMIN)
+    ├── General /config
+    ├── Usuarios /config/usuarios
+    └── Integraciones /config/integraciones
+```
+
+### Reglas de jerarquía visual
+
+```
+H1 — Una por página (título de la sección)
+H2 — Subsecciones del contenido principal
+H3 — Títulos de tarjetas o paneles
+H4 — Etiquetas de grupos dentro de formularios
+Texto: Sans-serif, 16px base, 24px line-height
+Microcopy: 14px, color secundario
+```
+
+---
+
+## Navigation Patterns
+
+### Tabs (uso y cuándo)
+
+```
+USAR TABS cuando:
+- 3-6 vistas relacionadas del mismo contenido
+- El usuario necesita cambiar entre vistas frecuentemente
+- El contenido de cada tab es independiente
+
+EVITAR TABS cuando:
+- Hay más de 6 opciones (usar sidebar o dropdown)
+- Las vistas tienen jerarquía (usar breadcrumbs + sub-páginas)
+- En móvil con tabs de contenido largo (usar accordion)
+
+FORMATO:
+[Tab Activa] [Tab 2] [Tab 3] [Tab 4]
+─────────────────────────────────────
+[Contenido de Tab Activa]
+```
+
+### Drawer / Sidebar
+
+```
+USAR DRAWER cuando:
+- Navegación principal de la app (5+ secciones)
+- El estado de navegación se reutiliza entre páginas
+
+COLAPSABLE: sí (desktop: sidebar fijo 240px ↔ iconos 64px, móvil: overlay)
+
+ESTRUCTURA SIDEBAR:
+Logo
+─────────────────
+Sección Principal (con ícono)
+  ├─ Subsección activa (highlight)
+  └─ Subsección 2
+Sección 2 (con ícono)
+─────────────────
+[Divider]
+Configuración (ícono engranaje)
+Avatar del usuario + nombre
+```
+
+### Breadcrumbs
+
+```
+USAR cuando: el usuario está 2+ niveles de profundidad
+
+FORMATO:
+Inicio > Usuarios > Ana López > Editar
+
+REGLAS:
+- Último item = página actual (no es link, no clickeable)
+- Máximo 4 niveles visibles (truncar intermedios con "...")
+- En móvil: mostrar solo el nivel inmediato anterior con "← Anterior"
+```
+
+---
+
+## Responsive Breakpoints — Decisiones por Pantalla
+
+```
+Pantalla: Gestión de Usuarios (tabla con acciones)
+
+DESKTOP (≥1024px):
+  Sidebar fijo 240px + tabla completa con todas las columnas
+
+TABLET (768px-1023px):
+  Sidebar colapsado a iconos 64px + tabla con columnas reducidas
+  (ocultar: Último acceso, Rol — accesibles en detalle del panel lateral)
+
+MÓVIL (<768px):
+  Sidebar = drawer oculto (abrir con hamburger icon)
+  Tabla → Lista vertical de cards
+  Cada card: Avatar + Nombre + Email + [Acciones: ...]
+  Búsqueda: campo expandible (lupa → input)
+  Paginación: scroll infinito o "Cargar más"
+
+BREAKPOINT KEY DECISIONS:
+- ¿Tabla o cards en móvil? → Cards (tabla no es usable en pantallas <480px)
+- ¿Sidebar o drawer en tablet? → Íconos (preserve space for content)
+- ¿Modal o página nueva en móvil? → Página nueva (modales en móvil son difíciles de cerrar)
+```
+
+---
+
+## Checklist de Entrega de Wireframe
+
+```
+PANTALLA
+[ ] Nombre y ruta URL
+[ ] Propósito en 1 oración
+[ ] Layout descrito (grid, columnas, proporciones)
+[ ] Todos los elementos nombrados (no "botón" — "botón Crear Usuario")
+[ ] Jerarquía tipográfica especificada (H1/H2/texto/microcopy)
+[ ] Comportamientos interactivos descritos (hover, click, debounce, etc.)
+
+ESTADOS
+[ ] Empty state definido
+[ ] Loading state definido
+[ ] Error state definido
+[ ] Estado de éxito (si aplica)
+
+FLUJO
+[ ] Entradas a esta pantalla (¿desde dónde se llega?)
+[ ] Salidas de esta pantalla (¿a dónde va?)
+[ ] Acciones con API calls marcadas con {API: ...}
+[ ] Manejo de errores de API especificado
+
+RESPONSIVE
+[ ] Comportamiento en desktop descrito
+[ ] Comportamiento en tablet descrito
+[ ] Comportamiento en móvil descrito
+[ ] Decisiones de breakpoint justificadas
+```