Enhance Glyph
Improve existing pictogram glyph in viz/ → audit render, diagnose issues, targeted mods, re-render, compare before/after. Works skill/agent/team.
Use When
- Glyph renders poor small sizes (details lost, shapes merge)
- Metaphor unclear / mismatch entity
- Proportion issues (too big/small, off-center)
- Neon glow overpowers or underwhelms
- Good in 1 palette, poor others
- Batch improve after new palettes / pipeline change
In
- Required: Entity type —
skill, agent, team
- Required: Entity ID (e.g.,
commit-changes, mystic, tending)
- Required: Specific issue (readability, proportions, glow, palette compat)
- Optional: Reference glyph showing desired quality
- Optional: Target palette(s) (default: all)
Do
Step 1: Audit
Examine current, identify issues.
- Locate glyph fn by entity type:
- Skills:
viz/R/primitives*.R (19 domain files), map viz/R/glyphs.R
- Agents:
viz/R/agent_primitives.R, map viz/R/agent_glyphs.R
- Teams:
viz/R/team_primitives.R, map viz/R/team_glyphs.R
- Read fn structure:
- How many layers?
- Which primitives?
- Scale + position?
- View 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
- Check 2-3 other palettes
- View icon (
48px) + panel (160px)
- Score on 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)? |
+----------------+------+-----------------------------------------------+
- Identify 1-2 lowest dims → enhancement targets
→ Clear diagnosis. Specific: "proportions: uses 40% canvas" not "looks bad."
If err: fn missing or entity not in *_glyphs.R → glyph not created → use create-glyph.
Step 2: Diagnose
Root cause.
- Readability:
- Too many fine details merge small?
- Low contrast between elements?
- Lines too thin (< 1.5
size at s=1.0)?
- Elements too close?
- Proportion:
- Scale
s too small/large?
- Center offset from (50, 50)?
- Elements beyond safe area (10-90)?
- Glow:
- Stroke width +
ggfx::with_outer_glow():
- Thin lines → glow fuzzy
- Thick fills → excessive bloom
- Multiple overlapping → compound glow hot spots
- Palette compat:
- Hardcoded colors not
col/bright?
- Low-contrast palettes (cividis, mako) make invisible?
- Relies on color variation some palettes lack?
- Document specific root cause each issue
→ Root causes point to code changes. "Too small" → "s=0.6, should be 0.8." "Glow overwhelms" → "3 overlapping filled polygons each generate glow."
If err: root cause not obvious from code → render isolation w/ diff params. render_glyph() single glyph to test.
Step 3: Modify
Edit fn → targeted fixes.
- Open file containing fn
- Mods per diagnosis:
- Scale/proportion: Adjust
s multiplier or element offsets
- Readability: Simplify, increase stroke width, spacing
- Glow balance: Reduce overlapping fills, outlines where bloom
- Palette compat: All colors from
col/bright, alpha for depth
- Follow 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
}
- Preserve signature — no param change
- Minimal mods — fix diagnosed, no redesign
→ Modified fn addresses Step 1-2 issues. Targeted + minimal.
If err: mods make other dims worse → revert, try diff. Needs redesign → create-glyph.
Step 4: Re-render
Render + verify. Always build.sh → handles platform + R binary. See render-icon-pipeline for flags.
Re-render by entity:
# 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
Verify output exists each palette
Check sizes — icons 2-15 KB (WebP):
- Under 2 KB: too simple or render failed
- Over 15 KB: too complex (too many layers)
→ Fresh icons each palette. Sizes in range.
If err: build errs → R console for specific. Common: missing paren, undefined primitives, non-list return. Renders but blank → layers outside canvas.
Step 5: Compare
Verify enhancement improved targets.
- Compare old/new:
- Cyberpunk at icon (48px) + panel (160px)
- ≥2 other palettes (light = turbo, dark = mako)
- Re-score dims from Step 1:
- Target dims ↑ ≥1 pt
- Non-target dims no ↓
- If in force-graph, test there:
- HTTP server:
python3 -m http.server 8080 from viz/
- Load graph, find entity node
- Verify renders default zoom + zoomed in
- Document changes + improvement
→ Measurable improvement on targets, no regression others. Better both sizes + all palettes.
If err: marginal improvement or regression → revert, reconsider diagnosis. Sometimes orig limit = inherent to metaphor → metaphor itself needs change (escalate create-glyph).
Check
Traps
- Over-enhance: Fix 1 + tweak all. Stick to diagnosed.
- Break contract: Sig change breaks pipeline. 5-param contract immutable.
- Palette-specific opt: Perfect cyberpunk but poor viridis. Check 3+ palettes.
- Ignore small-size: Beautiful 160px that blobs at 48px = fail.
- Forget re-render: Edit fn no build → changes invisible.
- Wrong build cmd: Skills
build-icons.R, agents build-agent-icons.R, teams build-team-icons.R.
→
1---2name: enhance-glyph-103description: Improve an existing R-based pictogram glyph for the visualization layer. Covers visual audit of the current glyph, diagnosis of specific issues (proportions, readability, glow balance), targeted modifications to the glyph function, re-rendering, and before/after comparison. Works for skill, agent, and team glyphs. Use when a glyph renders poorly at small sizes, its visual metaphor is unclear, it has proportion issues, the neon glow effect is unbalanced, or after adding new palettes or changing the rendering pipeline.4license: MIT5---67# Enhance Glyph89Improve existing pictogram glyph in `viz/` → audit render, diagnose issues, targeted mods, re-render, compare before/after. Works skill/agent/team.1011## Use When1213- Glyph renders poor small sizes (details lost, shapes merge)14- Metaphor unclear / mismatch entity15- Proportion issues (too big/small, off-center)16- Neon glow overpowers or underwhelms17- Good in 1 palette, poor others18- Batch improve after new palettes / pipeline change1920## In2122- **Required**: Entity type — `skill`, `agent`, `team`23- **Required**: Entity ID (e.g., `commit-changes`, `mystic`, `tending`)24- **Required**: Specific issue (readability, proportions, glow, palette compat)25- **Optional**: Reference glyph showing desired quality26- **Optional**: Target palette(s) (default: all)2728## Do2930### Step 1: Audit3132Examine current, identify issues.33341. Locate glyph fn by entity type:35 - **Skills**: `viz/R/primitives*.R` (19 domain files), map `viz/R/glyphs.R`36 - **Agents**: `viz/R/agent_primitives.R`, map `viz/R/agent_glyphs.R`37 - **Teams**: `viz/R/team_primitives.R`, map `viz/R/team_glyphs.R`382. Read fn structure:39 - How many layers?40 - Which primitives?41 - Scale + position?423. View rendered output:43 - Skills: `viz/public/icons/cyberpunk/<domain>/<skillId>.webp`44 - Agents: `viz/public/icons/cyberpunk/agents/<agentId>.webp`45 - Teams: `viz/public/icons/cyberpunk/teams/<teamId>.webp`46 - Check 2-3 other palettes47 - View icon (~48px) + panel (~160px)484. Score on **quality dimensions**:4950```text51Glyph Quality Dimensions:52+----------------+------+-----------------------------------------------+53| Dimension | 1-5 | Assessment Criteria |54+----------------+------+-----------------------------------------------+55| Readability | | Recognizable at 48px? Clear at 160px? |56| Proportions | | Well-centered? Good use of the 100x100 canvas?|57| Metaphor | | Does the shape clearly represent the entity? |58| Glow balance | | Glow enhances without overwhelming? |59| Palette compat | | Looks good across cyberpunk + viridis palettes?|60| Complexity | | Appropriate layer count (not too busy/sparse)? |61+----------------+------+-----------------------------------------------+62```63645. Identify 1-2 lowest dims → enhancement targets6566→ Clear diagnosis. Specific: "proportions: uses 40% canvas" not "looks bad."6768If err: fn missing or entity not in `*_glyphs.R` → glyph not created → use `create-glyph`.6970### Step 2: Diagnose7172Root cause.73741. **Readability**:75 - Too many fine details merge small?76 - Low contrast between elements?77 - Lines too thin (< 1.5 `size` at s=1.0)?78 - Elements too close?792. **Proportion**:80 - Scale `s` too small/large?81 - Center offset from (50, 50)?82 - Elements beyond safe area (10-90)?833. **Glow**:84 - Stroke width + `ggfx::with_outer_glow()`:85 - Thin lines → glow fuzzy86 - Thick fills → excessive bloom87 - Multiple overlapping → compound glow hot spots884. **Palette compat**:89 - Hardcoded colors not `col`/`bright`?90 - Low-contrast palettes (cividis, mako) make invisible?91 - Relies on color variation some palettes lack?925. Document specific root cause each issue9394→ Root causes point to code changes. "Too small" → "s=0.6, should be 0.8." "Glow overwhelms" → "3 overlapping filled polygons each generate glow."9596If err: root cause not obvious from code → render isolation w/ diff params. `render_glyph()` single glyph to test.9798### Step 3: Modify99100Edit fn → targeted fixes.1011021. Open file containing fn1032. Mods per diagnosis:104 - **Scale/proportion**: Adjust `s` multiplier or element offsets105 - **Readability**: Simplify, increase stroke width, spacing106 - **Glow balance**: Reduce overlapping fills, outlines where bloom107 - **Palette compat**: All colors from `col`/`bright`, alpha for depth1083. Follow **contract**:109 ```r110 glyph_name <- function(cx, cy, s, col, bright) {111 # cx, cy = center (50, 50)112 # s = scale (1.0 = ~70% of canvas)113 # col = domain color, bright = brightened variant114 # Returns: list() of ggplot2 layers115 }116 ```1174. Preserve signature — no param change1185. Minimal mods — fix diagnosed, no redesign119120→ Modified fn addresses Step 1-2 issues. Targeted + minimal.121122If err: mods make other dims worse → revert, try diff. Needs redesign → `create-glyph`.123124### Step 4: Re-render125126Render + verify. Always `build.sh` → handles platform + R binary. See [render-icon-pipeline](../render-icon-pipeline/SKILL.md) for flags.1271281. Re-render by entity:129130 ```bash131 # From project root — use --no-cache to force re-render of modified glyph132 bash viz/build.sh --only <domain> --no-cache # skills133 bash viz/build.sh --type agent --only <id> --no-cache # agents134 bash viz/build.sh --type team --only <id> --no-cache # teams135 ```1361372. Verify output exists each palette1383. Check sizes — icons 2-15 KB (WebP):139 - Under 2 KB: too simple or render failed140 - Over 15 KB: too complex (too many layers)141142→ Fresh icons each palette. Sizes in range.143144If err: build errs → R console for specific. Common: missing paren, undefined primitives, non-list return. Renders but blank → layers outside canvas.145146### Step 5: Compare147148Verify enhancement improved targets.1491501. Compare old/new:151 - Cyberpunk at icon (48px) + panel (160px)152 - ≥2 other palettes (light = turbo, dark = mako)1532. Re-score dims from Step 1:154 - Target dims ↑ ≥1 pt155 - Non-target dims no ↓1563. If in force-graph, test there:157 - HTTP server: `python3 -m http.server 8080` from `viz/`158 - Load graph, find entity node159 - Verify renders default zoom + zoomed in1604. Document changes + improvement161162→ Measurable improvement on targets, no regression others. Better both sizes + all palettes.163164If err: marginal improvement or regression → revert, reconsider diagnosis. Sometimes orig limit = inherent to metaphor → metaphor itself needs change (escalate `create-glyph`).165166## Check167168- [ ] Audited w/ specific issue diagnosis169- [ ] Root cause each issue170- [ ] Mods targeted to diagnosed (no over-edit)171- [ ] Fn contract preserved (sig unchanged)172- [ ] Re-rendered all palettes173- [ ] Before/after shows target improvement174- [ ] No regression non-target175- [ ] Sizes 2-15 KB WebP176- [ ] Renders correctly force-graph (if applicable)177178## Traps179180- **Over-enhance**: Fix 1 + tweak all. Stick to diagnosed.181- **Break contract**: Sig change breaks pipeline. 5-param contract immutable.182- **Palette-specific opt**: Perfect cyberpunk but poor viridis. Check 3+ palettes.183- **Ignore small-size**: Beautiful 160px that blobs at 48px = fail.184- **Forget re-render**: Edit fn no build → changes invisible.185- **Wrong build cmd**: Skills `build-icons.R`, agents `build-agent-icons.R`, teams `build-team-icons.R`.186187## →188189- [create-glyph](../create-glyph/SKILL.md) — new glyph scratch (enhancement insufficient)190- [audit-icon-pipeline](../audit-icon-pipeline/SKILL.md) — detect which need enhance pipeline-wide191- [render-icon-pipeline](../render-icon-pipeline/SKILL.md) — full pipeline after enhancements192- [ornament-style-mono](../ornament-style-mono/SKILL.md) — design principles applied to composition193- [chrysopoeia](../chrysopoeia/SKILL.md) — value extraction parallels optimization (amplify gold, remove dross)