Enhance Glyph

Improve an existing pictogram glyph in the viz/ visualization layer — audit its current rendering, diagnose visual issues, apply targeted modifications, re-render, and compare before/after. Works for skill, agent, and team glyphs.

When to Use

• A glyph renders poorly at small sizes (details lost, shapes merge)
• A glyph's visual metaphor is unclear or doesn't match the entity it represents
• A glyph has proportion issues (too large, too small, off-center)
• The neon glow effect overpowers or underwhelms the glyph
• A glyph looks good in one palette but poor in others
• Batch improvement after adding new palettes or changing the rendering pipeline

Inputs

• Required: Entity type — skill, agent, or team
• Required: Entity ID of the glyph to enhance (e.g., commit-changes, mystic, tending)
• Required: Specific issue to address (readability, proportions, glow, palette compat)
• Optional: Reference glyph that demonstrates the desired quality level
• Optional: Target palette(s) to optimize for (default: all palettes)

Procedure

Step 1: Audit — Assess Current State

Examine the current glyph and identify specific issues.

1. Locate the glyph function based on entity type:
   • Skills: viz/R/primitives*.R (19 domain-grouped files), mapped in viz/R/glyphs.R
   • Agents: viz/R/agent_primitives.R, mapped in viz/R/agent_glyphs.R
   • Teams: viz/R/team_primitives.R, mapped in viz/R/team_glyphs.R
2. Read the glyph function to understand its structure:
   • How many layers does it use?
   • What primitives does it call?
   • What are the scale factors and positioning?
3. View the rendered output:
   • Skills: viz/public/icons/cyberpunk/<domain>/<skillId>.webp
   • Agents: viz/public/icons/cyberpunk/agents/<agentId>.webp
   • Teams: viz/public/icons/cyberpunk/teams/<teamId>.webp
   • If available, check 2-3 other palettes for cross-palette rendering
   • View at both icon size (~48px in the graph) and panel size (~160px in the detail panel)
4. Score the glyph on the quality dimensions:

Glyph Quality Dimensions:
+----------------+------+-----------------------------------------------+
| Dimension      | 1-5  | Assessment Criteria                           |
+----------------+------+-----------------------------------------------+
| Readability    |      | Recognizable at 48px? Clear at 160px?         |
| Proportions    |      | Well-centered? Good use of the 100x100 canvas?|
| Metaphor       |      | Does the shape clearly represent the entity?   |
| Glow balance   |      | Glow enhances without overwhelming?            |
| Palette compat |      | Looks good across cyberpunk + viridis palettes?|
| Complexity     |      | Appropriate layer count (not too busy/sparse)? |
+----------------+------+-----------------------------------------------+

5. Identify the 1-2 dimensions with the lowest scores — these are the enhancement targets

Expected: A clear diagnosis of what's wrong with the glyph and which dimensions to improve. The audit should be specific: "proportions: glyph uses only 40% of canvas" not "looks bad."

On failure: If the glyph function is missing or the entity isn't in its *_glyphs.R mapping, the glyph may not have been created yet — use create-glyph instead.

Step 2: Diagnose — Root Cause Analysis

Determine why the identified issues exist.

1. For readability issues:
   • Too many fine details that merge at small sizes?
   • Insufficient contrast between glyph elements?
   • Lines too thin (< 1.5 size at s=1.0)?
   • Elements too close together?
2. For proportion issues:
   • Scale factor s too small or too large?
   • Center offset from (50, 50)?
   • Elements extending beyond the safe area (10-90 range)?
3. For glow issues:
   • Glyph stroke width interacts with ggfx::with_outer_glow():
     • Thin lines: glow makes them fuzzy
     • Thick fills: glow adds excessive bloom
   • Multiple overlapping elements: compound glow creates hot spots
4. For palette compatibility issues:
   • Glyph uses hardcoded colors instead of col/bright parameters?
   • Low-contrast palettes (cividis, mako) make the glyph invisible?
   • The glyph relies on color variation that some palettes don't provide?
5. Document the specific root cause for each issue

Expected: Root causes that directly point to code changes. "The glyph is too small" -> "scale factor is 0.6 but should be 0.8." "Glow overwhelms" -> "three overlapping filled polygons each generate glow."

On failure: If the root cause isn't obvious from code inspection, render the glyph in isolation with different parameters to isolate the issue. Use render_glyph() with a single glyph to test.

Step 3: Modify — Apply Targeted Fixes

Edit the glyph function to address the diagnosed issues.

1. Open the file containing the glyph function
2. Apply modifications specific to the diagnosis:
   • Scale/proportion: Adjust s multiplier or element offsets
   • Readability: Simplify complex elements, increase stroke width, add spacing
   • Glow balance: Reduce overlapping filled areas, use outlines where fills create bloom
   • Palette compat: Ensure all colors derive from col/bright parameters, add alpha for depth
3. Follow the glyph function contract:

   glyph_name <- function(cx, cy, s, col, bright) {
     # cx, cy = center (50, 50)
     # s = scale (1.0 = ~70% of canvas)
     # col = domain color, bright = brightened variant
     # Returns: list() of ggplot2 layers
   }
   

4. Preserve the function signature — do not change parameters
5. Keep modifications minimal: fix the diagnosed issues, don't redesign the entire glyph

Expected: A modified glyph function that addresses the specific issues identified in Steps 1-2. Changes are targeted and minimal — enhance, don't redesign.

On failure: If the modifications make other dimensions worse (e.g., fixing proportions breaks readability), revert and try a different approach. If the glyph needs a complete redesign, use create-glyph instead.

Step 4: Re-render — Generate Updated Icons

Render the modified glyph and verify the fix. Always use build.sh — it handles platform detection and R binary selection. See render-icon-pipeline for the full flag reference.

1. Re-render based on entity type:

   # From project root — use --no-cache to force re-render of modified glyph
   bash viz/build.sh --only <domain> --no-cache          # skills
   bash viz/build.sh --type agent --only <id> --no-cache # agents
   bash viz/build.sh --type team --only <id> --no-cache  # teams
   

2. Verify the output files exist at the expected path for each palette

3. Check file sizes — icons should be 2-15 KB (WebP):

   • Under 2 KB: glyph may be too simple or rendering failed
   • Over 15 KB: glyph may be too complex (too many layers)

Expected: Fresh icon files generated for all palettes. File sizes are in the expected range.

On failure: If the build script errors, check the R console output for the specific error. Common causes: missing closing parenthesis in the glyph function, referencing undefined primitives, or returning non-list from the function. If rendering succeeds but output is blank, the glyph layers may be outside the canvas bounds.

Step 5: Compare — Before/After Verification

Verify the enhancement improved the target dimensions.

1. Compare old and new renderings:
   • View the cyberpunk palette version at both icon (48px) and panel (160px) sizes
   • View at least 2 other palettes (one light like turbo, one dark like mako)
2. Re-score the quality dimensions from Step 1:
   • Target dimensions should improve by at least 1 point
   • Non-target dimensions should not decrease
3. If the glyph is used in the force-graph, test it there:
   • Start the HTTP server: python3 -m http.server 8080 from viz/
   • Load the graph and find the entity node
   • Verify the icon renders correctly at default zoom and when zoomed in
4. Document the changes made and the improvement achieved

Expected: Measurable improvement on the target dimensions with no regression on others. The glyph looks better at both sizes and across palettes.

On failure: If improvement is marginal or regression occurs, revert the changes and reconsider the diagnosis. Sometimes the original glyph's limitations are inherent to the metaphor, not the implementation — in that case, the metaphor itself may need to change (escalate to create-glyph).

Validation Checklist

• Current glyph audited with specific issue diagnosis
• Root cause identified for each issue
• Modifications targeted to diagnosed issues (not over-edited)
• Glyph function contract preserved (signature unchanged)
• Icons re-rendered for all palettes
• Before/after comparison shows improvement on target dimensions
• No regression on non-target dimensions
• File sizes in expected range (2-15 KB WebP)
• Glyph renders correctly in force-graph context (if applicable)

Common Pitfalls

• Over-enhancement: Fixing one issue and then tweaking everything else. Stick to the diagnosed issues
• Breaking the contract: Changing the function signature breaks the rendering pipeline. The 5-parameter contract is immutable
• Palette-specific optimization: Making the glyph perfect for cyberpunk but poor for viridis. Always check 3+ palettes
• Ignoring small-size rendering: A beautiful 160px icon that becomes a blob at 48px is a failed enhancement
• Forgetting to re-render: Editing the function without running the build command means the changes aren't visible
• Wrong build command: Skills use build-icons.R, agents use build-agent-icons.R, teams use build-team-icons.R

Related Skills

• create-glyph — create a new glyph from scratch (use when enhancement isn't enough)
• audit-icon-pipeline — detect which glyphs need enhancement across the pipeline
• render-icon-pipeline — run the full rendering pipeline after enhancements
• ornament-style-mono — visual design principles that apply to glyph composition
• chrysopoeia — value extraction methodology parallels glyph optimization (amplify gold, remove dross)