Agent-almanac enhance-glyph

install

source · Clone the upstream repo

git clone https://github.com/pjt222/agent-almanac

Claude Code · Install into ~/.claude/skills/

T=$(mktemp -d) && git clone --depth=1 https://github.com/pjt222/agent-almanac "$T" && mkdir -p ~/.claude/skills && cp -r "$T/i18n/de/skills/enhance-glyph" ~/.claude/skills/pjt222-agent-almanac-enhance-glyph-a1cd36 && rm -rf "$T"

manifest: i18n/de/skills/enhance-glyph/SKILL.md

source content

Glyphe verbessern

Eine bestehende Piktogramm-Glyphe in der

viz/

-Visualisierungsschicht verbessern — das aktuelle Rendering ueberpruefen, visuelle Probleme diagnostizieren, gezielte Modifikationen anwenden, neu rendern und Vorher/Nachher vergleichen. Funktioniert fuer Skill-, Agent- und Team-Glyphen.

Wann verwenden

Eine Glyphe rendert bei kleinen Groessen schlecht (Details gehen verloren, Formen verschmelzen)
Die visuelle Metapher einer Glyphe ist unklar oder passt nicht zur dargestellten Entitaet
Eine Glyphe hat Proportionsprobleme (zu gross, zu klein, dezentriert)
Der Neon-Glow-Effekt uebertrifft oder unterdrueckt die Glyphe
Eine Glyphe sieht in einer Palette gut aus, aber in anderen schlecht
Batch-Verbesserung nach dem Hinzufuegen neuer Paletten oder Aenderungen an der Rendering-Pipeline

Eingaben

Erforderlich: Entitaetstyp —
```
skill
```
,
```
agent
```
oder
```
team
```
Erforderlich: Entitaets-ID der zu verbessernden Glyphe (z.B.
```
commit-changes
```
,
```
mystic
```
,
```
tending
```
)
Erforderlich: Spezifisches Problem (Lesbarkeit, Proportionen, Glow, Paletten-Kompatibilitaet)
Optional: Referenz-Glyphe, die das gewuenschte Qualitaetsniveau demonstriert
Optional: Zielpalette(n) zur Optimierung (Standard: alle Paletten)

Verfahren

Schritt 1: Pruefung — Aktuellen Zustand bewerten

Die aktuelle Glyphe untersuchen und spezifische Probleme identifizieren.

Die Glyphen-Funktion basierend auf dem Entitaetstyp lokalisieren:
- Skills:
```
viz/R/primitives*.R
```
  (19 domaenengruppierte Dateien), zugeordnet in
```
viz/R/glyphs.R
```
- Agents:
```
viz/R/agent_primitives.R
```
  , zugeordnet in
```
viz/R/agent_glyphs.R
```
- Teams:
```
viz/R/team_primitives.R
```
  , zugeordnet in
```
viz/R/team_glyphs.R
```
Die Glyphen-Funktion lesen, um ihre Struktur zu verstehen:
- Wie viele Ebenen verwendet sie?
- Welche Primitives ruft sie auf?
- Welche Skalierungsfaktoren und Positionierung sind gesetzt?
Die gerenderte Ausgabe ansehen:
- Skills:
```
viz/public/icons/cyberpunk/<domain>/<skillId>.webp
```
- Agents:
```
viz/public/icons/cyberpunk/agents/<agentId>.webp
```
- Teams:
```
viz/public/icons/cyberpunk/teams/<teamId>.webp
```
- Falls verfuegbar, 2-3 weitere Paletten fuer palettenuebergreifendes Rendering pruefen
- Bei Icon-Groesse (~48px im Graph) und Panel-Groesse (~160px im Detail-Panel) betrachten
Die Glyphe auf den Qualitaetsdimensionen bewerten:

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)? |
+----------------+------+-----------------------------------------------+

Die 1-2 Dimensionen mit den niedrigsten Bewertungen identifizieren — das sind die Verbesserungsziele

Erwartet: Eine klare Diagnose, was mit der Glyphe nicht stimmt und welche Dimensionen verbessert werden sollen. Die Pruefung sollte spezifisch sein: "Proportionen: Glyphe nutzt nur 40% der Leinwand", nicht "sieht schlecht aus".

Bei Fehler: Falls die Glyphen-Funktion fehlt oder die Entitaet nicht in ihrer

*_glyphs.R

-Zuordnung ist, wurde die Glyphe moeglicherweise noch nicht erstellt — stattdessen

create-glyph

verwenden.

Schritt 2: Diagnostizieren — Ursachenanalyse

Bestimmen, warum die identifizierten Probleme bestehen.

Bei Lesbarkeits-Problemen:
- Zu viele feine Details, die bei kleinen Groessen verschmelzen?
- Unzureichender Kontrast zwischen Glyphen-Elementen?
- Linien zu duenn (< 1.5
```
size
```
  bei s=1.0)?
- Elemente zu nah beieinander?
Bei Proportions-Problemen:
- Skalierungsfaktor
```
s
```
  zu klein oder zu gross?
- Zentrum von (50, 50) verschoben?
- Elemente dehnen sich ueber den sicheren Bereich (10-90) hinaus aus?
Bei Glow-Problemen:
- Glyphen-Strichbreite interagiert mit
```
ggfx::with_outer_glow()
```
  :
  - Duenne Linien: Glow macht sie unscharf
  - Dicke Fuellungen: Glow erzeugt uebertriebenes Leuchten
- Mehrere ueberlappende Elemente: zusammengesetzter Glow erzeugt Hotspots
Bei Palettenkompatibilitaets-Problemen:
- Glyphe verwendet hartcodierte Farben statt
```
col
```
  /
```
bright
```
  -Parameter?
- Kontrastarme Paletten (cividis, mako) machen die Glyphe unsichtbar?
- Die Glyphe haengt von Farbvariation ab, die manche Paletten nicht bieten?
Die spezifische Ursache fuer jedes Problem dokumentieren

Erwartet: Ursachen, die direkt auf Code-Aenderungen hinweisen. "Die Glyphe ist zu klein" -> "Skalierungsfaktor ist 0.6, sollte aber 0.8 sein." "Glow uebertrifft" -> "Drei ueberlappende gefuellte Polygone erzeugen jeweils Glow."

Bei Fehler: Falls die Ursache nicht offensichtlich aus der Code-Inspektion ist, die Glyphe isoliert mit verschiedenen Parametern rendern, um das Problem einzugrenzen.

render_glyph()

mit einer einzelnen Glyphe zum Testen verwenden.

Schritt 3: Modifizieren — Gezielte Korrekturen anwenden

Die Glyphen-Funktion bearbeiten, um die diagnostizierten Probleme zu beheben.

Die Datei oeffnen, die die Glyphen-Funktion enthaelt
Modifikationen entsprechend der Diagnose anwenden:
- Skalierung/Proportionen:
```
s
```
  -Multiplikator oder Element-Offsets anpassen
- Lesbarkeit: Komplexe Elemente vereinfachen, Strichbreite erhoehen, Abstaende vergroessern
- Glow-Balance: Ueberlappende gefuellte Bereiche reduzieren, Umrisse statt Fuellungen verwenden, wo Fuellungen Leuchten erzeugen
- Palettenkompatibilitaet: Sicherstellen, dass alle Farben von
```
col
```
  /
```
bright
```
  -Parametern abgeleitet werden, Alpha fuer Tiefe hinzufuegen

Dem Glyphen-Funktionsvertrag folgen:

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
}

Die Funktionssignatur beibehalten — Parameter nicht aendern
Modifikationen minimal halten: die diagnostizierten Probleme beheben, nicht die gesamte Glyphe neu gestalten

Erwartet: Eine modifizierte Glyphen-Funktion, die die in Schritten 1-2 identifizierten spezifischen Probleme behebt. Aenderungen sind gezielt und minimal — verbessern, nicht neu gestalten.

Bei Fehler: Falls die Modifikationen andere Dimensionen verschlechtern (z.B. Proportionsfix bricht Lesbarkeit), Aenderungen rueckgaengig machen und einen anderen Ansatz versuchen. Falls die Glyphe eine vollstaendige Neugestaltung benoetigt, stattdessen

create-glyph

verwenden.

Schritt 4: Neu rendern — Aktualisierte Icons generieren

Die modifizierte Glyphe rendern und die Korrektur verifizieren.

Basierend auf dem Entitaetstyp neu rendern:

Fuer Skills:

cd /mnt/d/dev/p/agent-almanac/viz
Rscript build-icons.R --only <domain> --no-cache

Fuer Agents:

cd /mnt/d/dev/p/agent-almanac/viz
Rscript build-agent-icons.R --only <agent-id> --no-cache

Fuer Teams:

cd /mnt/d/dev/p/agent-almanac/viz
Rscript build-team-icons.R --only <team-id> --no-cache

Ausgabedateien am erwarteten Pfad fuer jede Palette pruefen
Dateigroessen pruefen — Icons sollten 2-15 KB (WebP) sein:
- Unter 2 KB: Glyphe ist moeglicherweise zu einfach oder Rendering ist fehlgeschlagen
- Ueber 15 KB: Glyphe ist moeglicherweise zu komplex (zu viele Ebenen)

Erwartet: Frische Icon-Dateien fuer alle Paletten generiert. Dateigroessen im erwarteten Bereich.

Bei Fehler: Falls das Build-Skript Fehler ausgibt, die R-Konsolenausgabe auf den spezifischen Fehler pruefen. Haeufige Ursachen: fehlende schliessende Klammer in der Glyphen-Funktion, Referenzierung undefinierter Primitives oder Rueckgabe eines Nicht-Listen-Objekts. Falls das Rendering erfolgreich ist, aber die Ausgabe leer, koennten die Glyphen-Ebenen ausserhalb der Leinwandgrenzen liegen.

Schritt 5: Vergleichen — Vorher/Nachher-Verifikation

Ueberpruefen, ob die Verbesserung die Zieldimensionen verbessert hat.

Alte und neue Renderings vergleichen:
- Die Cyberpunk-Palettenversion bei Icon- (48px) und Panel-Groesse (160px) betrachten
- Mindestens 2 weitere Paletten pruefen (eine helle wie Turbo, eine dunkle wie Mako)
Die Qualitaetsdimensionen aus Schritt 1 erneut bewerten:
- Zieldimensionen sollten sich um mindestens 1 Punkt verbessern
- Nicht-Zieldimensionen sollten sich nicht verschlechtern
Falls die Glyphe im Force-Graph verwendet wird, dort testen:
- HTTP-Server starten:
```
python3 -m http.server 8080
```
  von
```
viz/
```
  aus
- Den Graph laden und den Entitaetsknoten finden
- Verifizieren, dass das Icon bei Standard-Zoom und beim Hineinzoomen korrekt rendert
Die vorgenommenen Aenderungen und die erzielte Verbesserung dokumentieren

Erwartet: Messbare Verbesserung auf den Zieldimensionen ohne Verschlechterung bei anderen. Die Glyphe sieht bei beiden Groessen und ueber Paletten hinweg besser aus.

Bei Fehler: Falls die Verbesserung marginal ist oder eine Verschlechterung auftritt, die Aenderungen rueckgaengig machen und die Diagnose ueberdenken. Manchmal sind die Einschraenkungen der urspruenglichen Glyphe dem Konzept inhaerent, nicht der Implementierung — in diesem Fall muss moeglicherweise die Metapher selbst geaendert werden (Eskalation zu

create-glyph

Validierungscheckliste

Aktuelle Glyphe mit spezifischer Problemdiagnose geprueft
Ursache fuer jedes Problem identifiziert
Modifikationen auf diagnostizierte Probleme ausgerichtet (nicht ueberarbeitet)
Glyphen-Funktionsvertrag beibehalten (Signatur unveraendert)
Icons fuer alle Paletten neu gerendert
Vorher/Nachher-Vergleich zeigt Verbesserung bei Zieldimensionen
Keine Verschlechterung bei Nicht-Zieldimensionen
Dateigroessen im erwarteten Bereich (2-15 KB WebP)
Glyphe rendert korrekt im Force-Graph-Kontext (falls zutreffend)

Haeufige Fehler

Ueberverbesserung: Ein Problem beheben und dann alles andere auch noch anpassen. Bei den diagnostizierten Problemen bleiben
Vertragsbruch: Die Funktionssignatur aendern bricht die Rendering-Pipeline. Der 5-Parameter-Vertrag ist unveraenderlich
Palettenspezifische Optimierung: Die Glyphe perfekt fuer Cyberpunk machen, aber schlecht fuer Viridis. Immer 3+ Paletten pruefen
Kleingeroessen-Rendering ignorieren: Ein schoenes 160px-Icon, das bei 48px zum Klecks wird, ist eine gescheiterte Verbesserung
Vergessen neu zu rendern: Die Funktion bearbeiten ohne den Build-Befehl auszufuehren bedeutet, dass die Aenderungen nicht sichtbar sind
Falscher Build-Befehl: Skills verwenden
```
build-icons.R
```
, Agents verwenden
```
build-agent-icons.R
```
, Teams verwenden
```
build-team-icons.R
```