EugineKosenko/majordom

analyze-fig

Analysiert einen Figma-Export (.fig) ohne Zugriff auf die Figma-API: Der Knotenbaum, Texte und Raster werden direkt aus der Datei gelesen, während die Kommentare des Autors, die nicht in der .fig enthalten sind, separat über MCP anhand eines Links abgerufen werden. Das Ergebnis sind Markdown-Dateien in spcfctn/ui/, die statt eines erneuten Figma-Lesens verwendet werden.

Wann nicht ausführen

Fragen zu einem bereits analysierten Layout („Was steht im Kommentar zum Filter …“, „Welche Spalten hat der Bildschirm…“) werden durch Lesen von spcfctn/ui/*.md beantwortet, nicht mit dieser Fertigkeit. Eine Analyse ist nur bei einer neuen oder aktualisierten .fig erforderlich, oder wenn die Antwort nicht in der Markdown-Datei vorhanden ist (siehe spcfctn-code.md).

Verzeichnisse (einziges Entwurfsverzeichnis draft, außerhalb von git)

• spcfctn/ui/draft/ — die eingehende .fig (und ggf. andere Entwürfe). Die Datei wird vom Benutzer abgelegt.
• spcfctn/ui/draft/<name>/ — das Ergebnis der Entpackung: message.json (alle Knoten), meta.json, images/, screens.json und screens.txt, sowie die gesammelten Kommentare (comments.json). Wird aus der .fig generiert und nicht mit git verfolgt. Es gibt keine separaten raw/ oder data/ Verzeichnisse (modeling.md).
• spcfctn/ui/*.md — das Ergebnis der Analyse; nur diese Dateien werden in git eingepflegt.

<name> ist der Dateiname ohne Erweiterung, in Kleinbuchstaben mit Bindestrichen (internal-interfaces).

Schritt 0 – Vorbereitung

• Finde das Projektverzeichnis spcfctn/. Falls es nicht existiert, bitte den Benutzer, es zu erstellen (spcfctn-code.md). Das Artefakt ui/ und sein Unterverzeichnis draft/ erstellst du selbst.
• Überprüfe spcfctn/ui/.gitignore (Repository des Artefakts): Es muss draft enthalten (siehe modeling.md); fehlende Einträge füge über gitignore.org hinzu.
• Fig-Datei: Der Benutzer gibt den Dateinamen an; falls keiner angegeben wird, liste spcfctn/ui/draft/*.fig auf und frage nach.
• Lies die CLAUDE.md des Projekts (Sprache, Konventionen) und vorhandene spcfctn/ui/*.md: Die Analyse muss deren Struktur und Begriffe fortsetzen, nicht von null beginnen.
• python3 und zstd müssen im PATH verfügbar sein.

Schritt 1 – Entpacken und Dekodieren

python3 ~/.claude/skills/analyze-fig/scripts/fig.py spcfctn/ui/draft/X.fig spcfctn/ui/draft/<name>

Gibt die Formatversion, die Anzahl der Knoten, Blobs und Bilder aus. Das Skript ist für Version 106 getestet; bei einer anderen Version oder einem Fehler darfst du das Format nicht erraten oder fremde Decoder verwenden – informiere den Benutzer. meta.json enthält exported_at: Die Exportzeit wird in Schritt 5 benötigt. message.json ist groß – drucke es nicht direkt aus.

Schritt 2 – In Abschnitte und Bildschirme zerlegen

python3 ~/.claude/skills/analyze-fig/scripts/screens.py spcfctn/ui/draft/<name>

Gibt eine Liste der Seiten, Abschnitte (Frames der obersten Ebene) und Bildschirme (deren Kinder) mit der Anzahl der Texte und Raster aus. Die gesamte Essenz steckt in screens.txt: Für jeden Bildschirm sind die Textebenen von oben nach unten und von links nach rechts gruppiert (so werden Filter, Spaltenüberschriften und Schaltflächen gelesen), plus Verweise auf Raster.

• Vergleiche die Anzahlen mit den erwarteten Werten (z.B. aus altem Markdown); eine Abweichung ist ein Grund anzuhalten.
• Textebenen sehen keine Elemente ohne Text (reine Symbole) und den Inhalt von Rastern. Öffne für jedes Raster aus images/ die Datei (Read) und beschreibe, was in den Textebenen fehlt; kennzeichne, dass dies aus dem Bild gelesen wurde. Der Baum und die Texte sind die Hauptquelle; Bilder dienen als Ergänzung.
• Komponenten-Instanzen (INSTANCE) können überschriebene Texte haben, die das Skript nicht sieht; screens.txt warnt davor.

Schritt 3 – spcfctn/ui/*.md schreiben

• Ein Markdown-Dokument pro Abschnitt (oder pro Datei, wenn es nur einen Abschnitt gibt). Wenn die Datei bereits existiert, lies sie vollständig und aktualisiere sie – überschreibe sie nicht: Markdown-Dateien werden nur vom Agenten gepflegt, aber frühere Klarstellungen dürfen nicht verloren gehen.
• Die Sprache der Prosa richtet sich nach CLAUDE.md des Projekts.
• Struktur (Beispiel in spcfctn/ui/internal-dashboard.md im Projekt job/vale/kylada): Einleitung mit Quelle und Prüfung (was gelesen wurde, Exportdatum, Anzahl Bildschirme und Texte), Layout-Leseregeln, Zuordnung von UI-Beschriftungen zu internen Begriffen, Bildschirme in Reihenfolge (Filter in Layout-Reihenfolge, Listenschaltfläche, Spalten, Zeilenaktionen), offene Fragen.
• Alles, was deine eigene Interpretation ist und nicht aus dem Layouttext oder einem Kommentar stammt, kennzeichne als inferred.
• Projektregeln zum Lesen von Layouts (z.B. dass ein Select unter einer Spaltenüberschrift die Sortierung steuert) entnimmst du der CLAUDE.md des Projekts und wendest sie an – erfinde keine eigenen Regeln.

Schritt 4 – Kommentare über MCP anhand eines Links abrufen

Kommentare sind nicht in der .fig enthalten (überprüft): Sie verbleiben auf dem Figma-Server.

• Ein Link zur Datei in Figma ist erforderlich (mit oder ohne node-id). Falls keiner vorhanden ist, fordere den Benutzer auf, einen bereitzustellen.
• Verwende ausschließlich das MCP-Tool comments des Figma-MCP-Servers, der im Projekt eingebunden ist (den Namen entnimmst du der Liste der verbundenen Server); der Parameter file ist der Link. Wenn ein solches Tool nicht existiert, informiere den Benutzer. Der offizielle figma-cs Server liefert keine Kommentare; verwende nicht direkt die REST-API mit Token und greife nicht auf .env zu.
• Ein Aufruf ohne node_id liefert alle Kommentare der Datei mit Verzweigungen (Nummer, Datum, Status, Knoten @id, Text, Antworten). Setze refresh nicht unnötig. Der Kommentar-Endpunkt wird separat vom Lesen der Datei gezählt und funktioniert auch, wenn das Lesen 429 ergab.
• Zuordnung zum Bildschirm:
  • Stimmt @id mit der ID eines Bildschirms aus screens.json überein, ist der Bildschirm identifiziert;
  • Gehört @id zu einem Abschnitt oder einer Seite, wird der Bildschirm anhand der Geometrie ermittelt; dazu werden die node_id und der node_offset des Kommentars benötigt. Erstelle Zeilen im Format SCHLÜSSEL KNOTEN X Y (z.B. #144 979:3 500 5471) und übergib sie an: python3 ~/.claude/skills/analyze-fig/scripts/place.py spcfctn/ui/draft/<name> < zeilen. Ausgabe: Schlüssel, Abschnitt, Bildschirm; oder Grund und nächster Bildschirm, falls der Punkt nicht auf einem Bildschirm liegt.
  • Überprüfe die Ausgabe: Das comments-Tool kann den node_offset weglassen (so war es zum Zeitpunkt der Erstellung dieser Fertigkeit). In diesem Fall können Kommentare zu Abschnitten oder Seiten nicht eindeutig zugeordnet werden: Rate den Bildschirm nicht anhand des Textes, sondern ordne sie dem Abschnitt zu, kennzeichne sie mit Bildschirm nicht bestimmt und teile dem Benutzer mit, dass für eine Auflösung der Offset des Kommentars benötigt wird.
• Antworten (↳) gehören zum übergeordneten Thread.

Schritt 5 – Prüfen, ob die Kommentare mit der Datei übereinstimmen

Überprüfe für jeden Kommentar mit bestimmtem Bildschirm (und für die Kommentargruppe eines Abschnitts):

• Sind die im Kommentar genannten Felder, Spalten, Schaltflächen, Werte in den Textebenen dieses Bildschirms vorhanden (Amount of integrated services ↔ Spalte Services; Zitate in Anführungszeichen; Wertelisten).
• Widerspricht der Kommentar dem Layout (Anzahl der Spalten, Reihenfolge, Elementtyp, „Filter vorhanden“ / „nicht vorhanden“).
• Datum: Ist der Kommentar neuer als exported_at aus meta.json, ist der Export veraltet. Fordere dann einen neuen Export in spcfctn/ui/draft/ an.
• Fehlt der Knoten des Kommentars in der Datei (gelöscht oder umbenannt), handelt es sich um einen verwaisten Kommentar.
• Kommentar ohne Bildschirm und ohne erkennbaren Inhalt.

Fasse Abweichungen in einer kleinen Tabelle zusammen (Nummer #N, Bildschirm, Art der Abweichung) und frage den Benutzer, was richtig ist: Korrigiere nicht stillschweigend und wähle nicht selbst zwischen Layout und Kommentar. Kennzeichne ungeklärte Punkte im Markdown bis zur Antwort als conflict.

Schritt 6 – Zusammenfassung schreiben

• Füge im Markdown einen Abschnitt mit den Autorenkommentaren hinzu: eine Zusammenfassung (was sie klären) und alle Kommentare nach Bildschirmen mit den Nummern #N. Wo ein Kommentar eine zuvor als inferred markierte Information präzisiert, korrigiere den Eintrag und verweise auf den Kommentar.
• Aktualisiere den Abschnitt „Verification“ in der Einleitung: Was gelesen wurde (.fig, Version, Exportdatum, Texte, Raster, Kommentare, Datum des Abrufs) und was nicht abgedeckt ist.
• Offene Fragen als separate Liste; Antworten des Benutzers verschiebe in „Resolved“.
• Committe nichts ohne Aufforderung. Fasse mündlich (auf Deutsch) zusammen: Anzahl Abschnitte, Bildschirme, Kommentare, Anzahl Abweichungen und was genau geklärt werden muss.

Was nicht zu tun ist

• Verwende nicht die Figma-REST-API mit Token, lies oder bearbeite nicht .env.
• Lies keinen fremden Code (kiwi-Decoder usw.): Das Format wird bereits durch scripts/ implementiert.
• Lege .fig und die Analyse (alles unter draft/) nicht in git ab.
• Rate den Bildschirm eines Kommentars nicht anhand des Textes und den Inhalt des Layouts nicht anhand eines Bildes, wenn Textebenen vorhanden sind.