--- name: metadatos description: Especialista en validación y generación de metadatos YAML (frontmatter) para archivos markdown del proyecto SyV, garantizando coherencia con estándares --- # Skill: Metadata Validator ## Competencia Especialista en validación y generación de metadatos YAML (frontmatter) para archivos `.md` del proyecto "Subordinación y Valor", garantizando cumplimiento de estándares y coherencia. ## Cuándo se Activa Automáticamente al: - Crear o editar archivos `.md` en carpetas de contenido (`0_proyecto/`, `1_trasfondo/`, `2_atlas/`, `3_personajes/`, `4_diegesis/`, `5_aventuras/`) - Ejecutar comando `/check-metadata` - Ejecutar comando `/suggest-tags` - Post-edición de archivos markdown (hook) ## Expertise ### Esquema de Metadatos Obligatorios **Campos SIEMPRE requeridos**: ```yaml --- title: Título del documento folder: ruta/relativa/desde/raiz description: Breve descripción del contenido --- ``` ### Campos Opcionales pero Recomendados **Para todos los archivos**: ```yaml tags: - tag1 - tag2 - tag3 ``` **Para cronología**: ```yaml fecha: YYYY-MM-DD region: Región, Subregión, Ciudad ``` **Para personajes** (IMPORTANTE): ```yaml facciones: - "Nombre Facción 1" - "Nombre Facción 2" alerta-spoilers: "Texto de advertencia sobre información sensible" ``` ### Convenciones de Formato 1. **Idioma**: Campos en inglés, contenido en español 2. **Formato de claves**: kebab-case para valores (palabras-separadas-por-guiones) 3. **Espaciado**: SIEMPRE espacio después de dos puntos (`:`) 4. **No tabs**: Solo espacios para indentación 5. **Arrays YAML**: Guiones con espacios (`- item`) ### Campos PROHIBIDOS ❌ **NUNCA usar campos en español**: - `titulo` (usar `title`) - `carpeta` (usar `folder`) - `descripcion` (usar `description`) - `layout` (no usar) - `author` (no usar) ## Capacidades ### 1. Validar Metadatos Existentes Verificar: - ✅ Campos obligatorios presentes (`title`, `folder`, `description`) - ✅ Formato YAML correcto (sintaxis, espaciado) - ✅ Campos en inglés - ✅ Ruta en `folder` es relativa y correcta - ✅ Tags apropiados (existen en corpus, no demasiado genéricos) - ✅ Campos específicos por tipo (personajes: `facciones` obligatorio) ### 2. Generar Metadatos Completos Para nuevos archivos: 1. Analizar contenido para extraer información 2. Determinar tipo de archivo (personaje/facción/cronología/etc.) 3. Generar frontmatter completo con campos apropiados 4. Sugerir tags relevantes basados en contenido ### 3. Sugerir Tags Buscar en corpus tags existentes que puedan aplicar: - Tags de ubicación (darsena, tuberias, cordoba, etc.) - Tags de personajes (nombre-apellido) - Tags de facciones (sia, arpistas, etc.) - Tags de conceptos (anatema-mecanico, qia, etc.) - Tags de períodos (caos, gran-guerra, actualidad-2178, etc.) - Tags de tipo (cronologia, relato, faccion, personaje, etc.) ### 4. Corregir Errores Comunes Detectar y corregir: - Campos en español → Convertir a inglés - Falta de espacio después de `:` → Agregar espacio - Tabulaciones → Convertir a espacios - Tags duplicados → Eliminar duplicados - Campo `facciones` faltante en personajes → Agregar (vacío o poblado) - Ruta absoluta en `folder` → Convertir a relativa ## Categorías de Tags ### Tags de Ubicación ``` # Ciudades principales darsena, cordoba, mendoza, el-paramo # Zonas de Dársena tuberias, barrios-del-muro, barrio-norte, microcentro zona-centro, zona-militar, isla-oriental, fuera-del-muro # Lugares específicos nueva-basilica, universidad-catolica, torres-hidroponicas crater, zona-exclusion, rio-de-la-plata # Regiones argentina, buenos-aires, pantano, delta ``` ### Tags de Personajes ``` # Formato: nombre-apellido (o apodo si es más conocido) damian-diconte, francisco-de-la-cruz, padre-rafa monsenor-miguel, hermana-superior-maria paco-el-puntero, sor-sofia ``` ### Tags de Facciones ``` # Oficiales sia, iglesia, iglesia-de-darsena ejercito, armada, prefectura, fuerzas-armadas gremio, la-union # Proscritas/Secretas arpistas, guardianes, guardianes-de-la-memoria criptografos, canales-ocultos, resistencia umbanda, cazadores-de-pesadillas, shipibo-conibo traficantes-de-almas ``` ### Tags de Conceptos Centrales ``` anatema-mecanico, corpus-licitus qia, inteligencia-artificial fin-de-los-secretos, gran-guerra, gran-colapso meteorito, crater mision-s-a-n-t-a herejia, tecnologia-prohibida ``` ### Tags de Períodos Históricos ``` mundo-antiguo (2020-2029) anos-del-caos (2029-2038) gran-guerra (2039-2047) fin-de-los-secretos (2048-2061) edad-oscura (2062-2160) confederacion-temprana (2161-2177) actualidad-2178 ``` ### Tags de Tipo de Documento ``` cronologia, relato, carta, cronica, diario faccion, personaje, arquetipo atlas, mapa, tecnologia constitucion, herejia guia, aventura, investigacion ``` ## Restricciones ### 1. Campos Obligatorios - ❌ NUNCA omitir `title`, `folder`, `description` - ✅ SIEMPRE incluir estos tres campos ### 2. Idioma - ❌ NUNCA usar campos en español - ✅ SIEMPRE inglés para campos (title, folder, description) ### 3. Formato YAML - ❌ NO usar tabulaciones - ✅ Solo espacios para indentación - ❌ NO omitir espacio después de `:` - ✅ `clave: valor` (espacio obligatorio) ### 4. Campo Facciones (Personajes) - ❌ NUNCA omitir campo `facciones` en personajes - ✅ SIEMPRE presente (puede estar vacío: `facciones: []`) ### 5. Ruta Carpeta - ❌ NO usar rutas absolutas - ✅ SIEMPRE relativa desde raíz del proyecto - ✅ Ejemplos: `3_personajes/principales`, `1_trasfondo/cronologia` ## Workflows ### Validar Archivo Existente 1. Leer frontmatter del archivo 2. Verificar campos obligatorios 3. Validar formato YAML (sintaxis, espaciado) 4. Comprobar idioma de campos (español) 5. Verificar campos específicos según tipo: - Personajes: `facciones` presente - Cronología: `fecha` y `region` apropiados 6. Validar tags (existen, no redundantes, apropiados) 7. Generar reporte: - ✅ Correctos - ⚠️ Advertencias (mejoras sugeridas) - ❌ Errores (deben corregirse) ### Generar Metadatos para Archivo Nuevo 1. Leer contenido del archivo 2. Determinar tipo (analizar ubicación y contenido): - `3_personajes/` → personaje - `1_trasfondo/facciones/` → facción - `1_trasfondo/cronologia/` → cronología - `2_atlas/` → ubicación/geografía - `4_diegesis/` → relato/carta/crónica 3. Extraer información del contenido: - Título (primer H1 o nombre archivo) - Descripción (primer párrafo o resumen) - Tags (conceptos clave mencionados) 4. Generar frontmatter completo: ```yaml --- title: [Extraído/generado] folder: [Ruta relativa] description: [Extraída/generada] tags: - [sugerencias basadas en contenido] # Campos específicos según tipo --- ``` ### Sugerir Tags 1. Leer contenido completo del archivo 2. Identificar menciones de: - Ubicaciones (Dársena, Córdoba, Túberías, etc.) - Personajes (nombres detectados) - Facciones (SIA, Arpistas, Iglesia, etc.) - Conceptos (Anatema, QIA, herejía, etc.) - Años/períodos (detectar rango temporal) 3. Buscar tags EXISTENTES en corpus que coincidan 4. Ordenar por relevancia: - Primero: Tags existentes (para mantener consistencia) - Segundo: Nuevos tags sugeridos (solo si necesarios) 5. Advertir si tag parece demasiado genérico 6. Presentar lista con categorías: ``` Tags sugeridos (EXISTENTES): - darsena - sia - damian-diconte Tags nuevos (CREAR solo si necesario): - [nuevo-concepto] (⚠️ Verificar si realmente necesario) ``` ## Ejemplos de Validación ### Ejemplo 1: Frontmatter Correcto ```yaml --- title: Damián DiConte folder: 3_personajes/principales description: Detective veterano de la Dirección Nacional de Seguridad, cuya investigación lo traslada de Córdoba a Dársena. tags: - damian-diconte - detective - cordoba - darsena - investigacion facciones: [] --- ``` **Validación**: ✅ TODO CORRECTO --- ### Ejemplo 2: Frontmatter con Errores ```yaml --- title: Damián DiConte folder: c:\Users\gcave\Projects\Dev\syv\3_personajes\principales description: Detective veterano... tags: - Damián - Detective --- ``` **Errores detectados**: - ❌ Campo `title` (inglés) → Usar `titulo` - ❌ Campo `folder` (inglés) → Usar `carpeta` - ❌ Ruta absoluta en `folder` → Usar relativa: `3_personajes/principales` - ❌ Campo `description` (inglés) → Usar `descripcion` - ❌ Tags con mayúsculas → Usar minúsculas kebab-case - ❌ Campo `facciones` faltante (es personaje) → Agregar **Corrección**: ```yaml --- title: Damián DiConte folder: 3_personajes/principales description: Detective veterano... tags: - damian-diconte - detective facciones: [] --- ``` --- ### Ejemplo 3: Personaje sin Campo Facciones ```yaml --- titulo: Dr. Francisco de la Cruz carpeta: 3_personajes/principales descripcion: Decano de Historia, líder de los Guardianes de la Memoria tags: - francisco-de-la-cruz --- ``` **Error detectado**: - ❌ Campo `facciones` OBLIGATORIO para personajes **Corrección**: ```yaml --- title: Dr. Francisco de la Cruz folder: 3_personajes/principales description: Decano de Historia, líder de los Guardianes de la Memoria tags: - francisco-de-la-cruz - guardianes - arpistas facciones: - "Guardianes de la Memoria" - "Arpistas" --- ``` --- ## Notas de Uso ### Prioridad de Tags Existentes SIEMPRE preferir tags que ya existen en el corpus para mantener consistencia. Antes de crear un tag nuevo, verificar si alguno existente puede servir: - ¿`detective` en lugar de `investigador`? - ¿`sia` en lugar de `inquisicion`? - ¿`darsena` en lugar de `ciudad-darsena`? ### Tags Demasiado Genéricos Advertir si usuario intenta tags como: - `personaje` (obvio en carpeta `3_personajes/`) - `historia` (demasiado amplio) - `importante` (subjetivo) ### Campo Alerta-Spoilers Si el personaje/facción tiene información secreta marcada como "**Información secreta (no exponer a jugadores):**", considerar agregar: ```yaml alerta-spoilers: "Este personaje/facción contiene información sensible que no debe revelarse prematuramente." ``` ### Rutas Relativas Correctas **CORRECTO**: - `0_proyecto/guias-para-colaboradores` - `1_trasfondo/cronologia` - `3_personajes/principales` **INCORRECTO**: - `c:\Users\gcave\Projects\Dev\syv\3_personajes` (absoluta) - `/3_personajes` (absoluta desde raíz del sistema) - `.\3_personajes` (notación relativa con punto)