audit-icon-pipeline

Audit Icon Pipeline

Detect missing glyphs, missing icons, and stale manifests by comparing registries against glyph mapping files, icon directories, and manifests. Produces a structured gap report covering skills, agents, and teams.

When to Use

• After adding new skills, agents, or teams to check if icons are needed
• Before a full pipeline render to identify what's missing
• After registry updates to ensure manifests are in sync
• Periodic health check of the icon pipeline

Inputs

• Optional: Entity type filter — skill, agent, team, or all (default: all)
• Optional: Palette to check (default: cyberpunk — the reference palette)

Procedure

Step 1: Read Registries

Collect all entity IDs from the source-of-truth registries.

1. Read skills/_registry.yml — extract all skill IDs across all domains
2. Read agents/_registry.yml — extract all agent IDs
3. Read teams/_registry.yml — extract all team IDs
4. Record counts: total skills, agents, teams

Expected: Three lists of entity IDs with counts matching total_skills, total_agents, total_teams.

On failure: If a registry file is missing, report the path and skip that entity type.

Step 2: Read Glyph Mappings

Collect all mapped entity IDs from the glyph mapping files.

1. Read viz/R/glyphs.R — extract all keys from SKILL_GLYPHS list
2. Read viz/R/agent_glyphs.R — extract all keys from AGENT_GLYPHS list
3. Read viz/R/team_glyphs.R — extract all keys from TEAM_GLYPHS list

Expected: Three lists of mapped IDs.

On failure: If a glyph file is missing, report it and mark all entities of that type as unmapped.

Step 3: Compute Missing Glyphs

Diff registry IDs against mapped IDs.

1. Missing skill glyphs: registry_skill_ids - mapped_skill_ids
2. Missing agent glyphs: registry_agent_ids - mapped_agent_ids
3. Missing team glyphs: registry_team_ids - mapped_team_ids

Expected: Lists of entity IDs that exist in registries but have no glyph function mapped.

On failure: If diff computation fails, verify ID formats match between registry and glyph files (e.g., underscores vs hyphens).

Step 4: Check Rendered Icons

Verify that mapped glyphs have corresponding rendered icon files.

1. For each mapped skill ID, check viz/public/icons/<palette>/<domain>/<skillId>.webp
2. For each mapped agent ID, check viz/public/icons/<palette>/agents/<agentId>.webp
3. For each mapped team ID, check viz/public/icons/<palette>/teams/<teamId>.webp
4. Check HD variants in viz/public/icons-hd/ with the same structure

Expected: Lists of entities with glyphs but missing rendered icons (standard and/or HD).

On failure: If the icon directory doesn't exist, the pipeline hasn't been run yet — report all as missing.

Step 5: Check Manifest Freshness

Compare manifest counts against registry counts.

1. Read viz/public/data/icon-manifest.json — count entries
2. Read viz/public/data/agent-icon-manifest.json — count entries
3. Read viz/public/data/team-icon-manifest.json — count entries
4. Compare against registry totals

Expected: Manifest counts match registry counts. Discrepancies indicate stale manifests.

On failure: If manifest files don't exist, the data pipeline needs to run first (node build-data.js && node build-icon-manifest.js).

Step 6: Detect Orphan Icons

Walk viz/public/icons*/ and flag WebP files whose <palette>/<domain>/<skillId> triple does not appear in icon-manifest.json.

1. Enumerate all WebP files: find viz/public/icons* -name "*.webp"
2. For each file, extract <domain>/<id> from its path
3. Check if <domain>/<id> has an entry in icon-manifest.json
4. Collect non-matching files as orphans — they exist on disk but are no longer referenced

# 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 (18 orphans per re-homing = 9 palettes × 2 sizes).

On failure: Delete orphans manually — they have no corresponding manifest entry and will not be served. Re-home events are rare, so manual cleanup is acceptable.

Step 7: Generate Gap Report

Produce a structured summary.

1. Format output as a clear table or list:

   === 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. Suggest next actions based on findings

Expected: A complete gap report with actionable next steps.

On failure: If all checks pass with zero gaps, report "Pipeline fully in sync" as a positive outcome.

Validation Checklist

• All three registries read successfully
• All three glyph mapping files checked
• Icon directories scanned for both standard and HD
• Manifest freshness verified
• Orphan icons checked (disk paths vs manifest)
• Gap report produced with counts and entity lists
• Actionable next steps provided

Common Pitfalls

• ID format mismatch: Registry uses kebab-case (create-skill), glyph maps may use snake_case keys — ensure comparison normalizes
• Palette assumption: Only checking cyberpunk palette misses palette-specific rendering gaps
• Empty directories: A domain directory existing but empty counts as "icons present" when globbing — check file existence, not directory existence
• HD not rendered: HD icons are in a separate directory tree (icons-hd/) — don't confuse with standard icons
• 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

Related Skills

• create-glyph — create a missing glyph identified by this audit
• enhance-glyph — improve quality of existing glyphs
• render-icon-pipeline — run the full pipeline to generate missing icons