--- name: audit-icon-pipeline locale: es source_locale: en source_commit: e4ffbae4 translator: claude translation_date: "2026-03-18" description: > Detectar glyphs faltantes, iconos y variantes HD comparando registros contra archivos de mapeo de glyphs, directorios de iconos y manifiestos. Reporta brechas para habilidades, agentes y equipos en todas las paletas. license: MIT allowed-tools: Read Bash Grep Glob metadata: author: Philipp Thoss version: "1.0" domain: visualization complexity: basic language: R tags: visualization, audit, icons, glyphs, pipeline, gap-analysis --- # Auditar Pipeline de Iconos Detectar glyphs faltantes, iconos ausentes y manifiestos desactualizados comparando registros contra archivos de mapeo de glyphs, directorios de iconos y manifiestos. Produce un informe estructurado de brechas que cubre habilidades, agentes y equipos. ## Cuando Usar - Despues de agregar nuevas habilidades, agentes o equipos para verificar si se necesitan iconos - Antes de un renderizado completo del pipeline para identificar lo que falta - Despues de actualizaciones del registro para asegurar que los manifiestos esten sincronizados - Verificacion periodica del estado del pipeline de iconos ## Entradas - **Opcional**: Filtro de tipo de entidad — `skill`, `agent`, `team` o `all` (predeterminado: `all`) - **Opcional**: Paleta a verificar (predeterminado: `cyberpunk` — la paleta de referencia) ## Procedimiento ### Paso 1: Leer Registros Recopilar todos los IDs de entidades de los registros fuente de verdad. 1. Leer `skills/_registry.yml` — extraer todos los IDs de habilidades en todos los dominios 2. Leer `agents/_registry.yml` — extraer todos los IDs de agentes 3. Leer `teams/_registry.yml` — extraer todos los IDs de equipos 4. Registrar conteos: total de habilidades, agentes y equipos **Esperado:** Tres listas de IDs de entidades con conteos que coinciden con `total_skills`, `total_agents`, `total_teams`. **En caso de fallo:** Si un archivo de registro no existe, reportar la ruta y omitir ese tipo de entidad. ### Paso 2: Leer Mapeos de Glyphs Recopilar todos los IDs de entidades mapeados desde los archivos de mapeo de glyphs. 1. Leer `viz/R/glyphs.R` — extraer todas las claves de la lista `SKILL_GLYPHS` 2. Leer `viz/R/agent_glyphs.R` — extraer todas las claves de la lista `AGENT_GLYPHS` 3. Leer `viz/R/team_glyphs.R` — extraer todas las claves de la lista `TEAM_GLYPHS` **Esperado:** Tres listas de IDs mapeados. **En caso de fallo:** Si un archivo de glyphs no existe, reportarlo y marcar todas las entidades de ese tipo como no mapeadas. ### Paso 3: Calcular Glyphs Faltantes Calcular la diferencia entre IDs del registro e IDs mapeados. 1. Glyphs de habilidades faltantes: `registry_skill_ids - mapped_skill_ids` 2. Glyphs de agentes faltantes: `registry_agent_ids - mapped_agent_ids` 3. Glyphs de equipos faltantes: `registry_team_ids - mapped_team_ids` **Esperado:** Listas de IDs de entidades que existen en los registros pero no tienen funcion de glyph mapeada. **En caso de fallo:** Si el calculo de diferencia falla, verificar que los formatos de ID coincidan entre el registro y los archivos de glyph (p. ej., guiones vs guiones bajos). ### Paso 4: Verificar Iconos Renderizados Comprobar que los glyphs mapeados tienen archivos de icono renderizados correspondientes. 1. Para cada ID de habilidad mapeado, verificar `viz/public/icons///.webp` 2. Para cada ID de agente mapeado, verificar `viz/public/icons//agents/.webp` 3. Para cada ID de equipo mapeado, verificar `viz/public/icons//teams/.webp` 4. Verificar variantes HD en `viz/public/icons-hd/` con la misma estructura **Esperado:** Listas de entidades con glyphs pero sin iconos renderizados (estandar y/o HD). **En caso de fallo:** Si el directorio de iconos no existe, el pipeline aun no se ha ejecutado — reportar todos como faltantes. ### Paso 5: Verificar Frescura del Manifiesto Comparar conteos del manifiesto contra conteos del registro. 1. Leer `viz/public/data/icon-manifest.json` — contar entradas 2. Leer `viz/public/data/agent-icon-manifest.json` — contar entradas 3. Leer `viz/public/data/team-icon-manifest.json` — contar entradas 4. Comparar contra los totales del registro **Esperado:** Los conteos del manifiesto coinciden con los conteos del registro. Las discrepancias indican manifiestos desactualizados. **En caso de fallo:** Si los archivos de manifiesto no existen, el pipeline de datos necesita ejecutarse primero (`node build-data.js && node build-icon-manifest.js`). ### Step 6: Detect Orphan Icons Walk `viz/public/icons*/` and flag WebP files whose `//` triple does not appear in `icon-manifest.json`. 1. Enumerate all WebP files: `find viz/public/icons* -name "*.webp"` 2. For each file, extract `/` from its path 3. Check if `/` has an entry in `icon-manifest.json` 4. Collect non-matching files as orphans — they exist on disk but are no longer referenced ```bash # Quick orphan count per palette node -e " const fs = require('fs'); const manifest = JSON.parse(fs.readFileSync('viz/public/data/icon-manifest.json')); const ids = new Set(manifest.map(e => e.domain + '/' + e.id)); const orphans = require('child_process') .execSync('find viz/public/icons -name \"*.webp\"').toString().trim().split('\n') .filter(p => { const parts = p.split('/'); const id = parts.slice(-2).join('/').replace('.webp',''); return !ids.has(id); }); console.log('Orphans:', orphans.length); orphans.forEach(p => console.log(' ', p)); " ``` **Expected:** Zero orphans. Any orphans indicate skills re-homed to a different domain without cleanup. **On failure:** Delete orphans manually — they have no corresponding manifest entry and will not be served. ### Paso 6: Generar Informe de Brechas Producir un resumen estructurado. 1. Formatear la salida como una tabla o lista clara: ``` === Icon Pipeline Audit === MISSING GLYPHS (no glyph function): Skills: 5 missing — [list] Agents: 2 missing — [list] Teams: 0 missing MISSING ICONS (glyph exists, no rendered WebP): Standard (512px): 3 skills, 1 agent HD (1024px): 8 skills, 3 agents, 1 team STALE MANIFESTS: icon-manifest.json: 320 entries vs 326 registry (stale) agent-icon-manifest.json: 66 entries vs 66 registry (OK) team-icon-manifest.json: 15 entries vs 15 registry (OK) ``` 2. Sugerir acciones siguientes basadas en los hallazgos **Esperado:** Un informe de brechas completo con pasos de accion concretos. **En caso de fallo:** Si todas las verificaciones pasan con cero brechas, reportar "Pipeline completamente sincronizado" como resultado positivo. ## Lista de Validacion - [ ] Los tres registros se leyeron exitosamente - [ ] Los tres archivos de mapeo de glyphs fueron verificados - [ ] Los directorios de iconos fueron escaneados tanto para estandar como para HD - [ ] La frescura del manifiesto fue verificada - [ ] El informe de brechas fue producido con conteos y listas de entidades - [ ] Se proporcionaron pasos de accion concretos ## Errores Comunes - **Discrepancia en formato de ID**: El registro usa kebab-case (`create-skill`), los mapeos de glyph pueden usar claves en snake_case — asegurar que la comparacion normalice los formatos - **Suposicion de paleta**: Solo verificar la paleta cyberpunk omite brechas de renderizado especificas de paleta - **Directorios vacios**: Un directorio de dominio existente pero vacio cuenta como "iconos presentes" al buscar con glob — verificar existencia de archivos, no de directorios - **HD no renderizado**: Los iconos HD estan en un arbol de directorios separado (`icons-hd/`) — no confundir con los iconos estandar ## Habilidades Relacionadas - [create-glyph](../create-glyph/SKILL.md) — crear un glyph faltante identificado por esta auditoria - [enhance-glyph](../enhance-glyph/SKILL.md) — mejorar la calidad de glyphs existentes - [render-icon-pipeline](../render-icon-pipeline/SKILL.md) — ejecutar el pipeline completo para generar iconos faltantes - [ ] Orphan icons checked (disk paths vs manifest) - **Orphans after re-homing**: When a skill's domain changes, `build.sh` creates icons at the new path but does NOT delete the old path — always run Step 6 orphan check after any domain migration