# SVG Skill - Analisi per introduzione di script Node locali di supporto Versione: 2026-04-24 Stato: proposta architetturale / decisione da validare --- ## 1) Obiettivo Valutare se conviene includere nella skill SVG script Node locali invocabili da riga di comando per funzioni matematiche, geometriche o trasformative che l'agente non esegue in modo abbastanza affidabile solo tramite reasoning testuale. L'obiettivo **non** e' spostare la logica della skill in codice, ma introdurre piccoli strumenti deterministici e ripetibili per operazioni numeriche o parametriche fragili. Esempi tipici: - supercerchio / superellipse; - generazione di path parametrici; - distribuzione di punti o elementi su arco/circonferenza; - calcolo di handle/control points; - trasformazioni geometriche ripetibili; - helper per viewBox, fit e bounding. --- ## 2) Decisione proposta ### Esito sintetico **GO condizionato** all'introduzione di script Node locali nella skill, ma solo per primitive computazionali ben delimitate. ### Principio guida Uno script locale ha senso quando svolge una funzione che e': - deterministica; - locale/offline; - difficile da eseguire con precisione solo via prompt; - utile in piu' task; - facile da testare; - limitata nel perimetro. ### Non-obiettivo Questi script **non** devono diventare: - un motore generale di generazione grafica; - una pipeline alternativa alla skill; - un insieme di utility poco governate; - un layer con dipendenze pesanti o runtime complicato. --- ## 3) Allineamento con best practice skill-oriented L'inclusione di script locali e' coerente con un design di skill ben strutturato quando: 1. la skill resta il punto di ingresso e di orchestrazione; 2. gli script sono usati solo dove la correttezza conta piu' della flessibilita'; 3. il comportamento e' spiegato in `SKILL.md` o nei workflow markdown; 4. gli script stanno **dentro la skill**, non dispersi nel repo; 5. esistono smoke test o esempi minimi eseguibili; 6. l'agente puo' capire chiaramente: - quando usare lo script, - con quali parametri, - cosa aspettarsi in output, - come degradare se lo script non e' disponibile. ### Regola architetturale La skill deve restare il **control plane**. Gli script devono essere solo **execution helpers** per parti deterministiche. --- ## 4) Perche' ha senso nella skill SVG La skill SVG lavora gia' su workflow che richiedono precisione e verificabilita': - validazione; - ottimizzazione conservativa; - conversioni; - export; - indicizzazione e discovery; - decisioni host-aware; - fallback espliciti. In questo contesto, aggiungere piccoli script Node per geometria o matematica avanzata e' coerente con il modello gia' adottato: - meno approssimazione numerica nel prompt; - output ripetibile; - piu' testabilita'; - piu' chiarezza tra parte creativa e parte computazionale. ### Caso emblematico: supercerchio / superellipse Il supercerchio e' un ottimo candidato perche': - richiede formule e sampling coerenti; - il path SVG risultante deve essere regolare e ripetibile; - il modello puo' descrivere bene l'intento, ma non sempre genera in modo robusto il path migliore; - un helper numerico locale riduce drift e inconsistenze. --- ## 5) Criteri di ammissibilita' per nuovi script Node Uno script puo' essere ammesso nella skill solo se soddisfa tutti o quasi tutti i criteri seguenti. ### 5.1 Determinismo A parita' di input, deve produrre sempre lo stesso output. ### 5.2 Perimetro stretto Deve risolvere una funzione specifica e non una famiglia indefinita di problemi. ### 5.3 Input e output chiari Devono essere documentati in modo minimale ma preciso. ### 5.4 Zero o pochissime dipendenze Preferenza forte per: - Node standard library; - nessuna dipendenza esterna. ### 5.5 Facilita' di smoke test Deve essere verificabile con 1-3 comandi semplici. ### 5.6 Valore riusabile Deve evitare di riscrivere ogni volta logica fragile o numerica. ### 5.7 Fallback documentato Se lo script non puo' essere usato, la skill deve saper: - dichiarare il limite; - offrire fallback semplificato; - non simulare un risultato ineseguito. --- ## 6) Casi in cui NON introdurre uno script Non introdurre script Node quando: - la trasformazione e' semplice e il modello la gestisce bene da solo; - il task e' piu' editoriale che computazionale; - il codice sarebbe solo una scorciatoia non riusabile; - il comportamento richiede librerie pesanti o runtime esterni; - lo script sostituirebbe la logica della skill invece di supportarla; - il risultato non e' facilmente verificabile. ### Esempi sconsigliati - generatore grafico generico "fai qualsiasi illustrazione"; - orchestratore completo di workflow SVG; - engine di layout troppo ampio; - wrapper complessi con molte dipendenze npm; - logica poco matematica ma molto testuale. --- ## 7) Tipi di script consigliati ### Classe A - Fortemente consigliati Primitive computazionali pure: - `superellipse.js` - `arc-points.js` - `polar-distribute.js` - `bezier-handles.js` - `fit-viewbox.js` - `rounded-corners.js` ### Classe B - Ammissibili con cautela Helper trasformativi locali: - normalizzazione parametrica di path; - conversione coordinate; - snapping geometrico semplice; - generazione shape procedurali limitate. ### Classe C - Da evitare nel pilot - composizione illustrativa multi-asset; - retrieval avanzato; - orchestrazione di librerie grafiche; - rendering complesso; - pipeline creative complete. --- ## 8) Posizionamento consigliato nel filesystem della skill Gli script dovrebbero vivere **dentro la skill**. ### Struttura consigliata ```text skills/svg/ ├── SKILL.md ├── optimize.md ├── validate.md ├── from-raster.md ├── export/ ├── assets/ ├── tools/ │ ├── superellipse.js │ ├── fit-viewbox.js │ └── README.md └── evals/ ``` ### Alternativa accettabile ```text skills/svg/scripts/ ``` ### Raccomandazione Preferire `tools/` se il focus e' su utility locali deterministiche. Preferire `scripts/` solo se il repo usa gia' fortemente quel naming per helper eseguibili. --- ## 9) Contratto operativo minimo per uno script Ogni script introdotto dovrebbe rispettare un contratto minimale. ### 9.1 CLI semplice Esempio: ```bash node skills/svg/tools/superellipse.js --width 256 --height 256 --n 4 --samples 128 ``` ### 9.2 Output machine-readable o direttamente utile Due modalita' ammissibili: #### A. Output JSON Buono per chaining e verifica. Esempio: ```json { "result": "ok", "shape": "superellipse", "width": 256, "height": 256, "n": 4, "samples": 128, "path_d": "M ..." } ``` #### B. Output SVG completo Buono per workflow molto specifici. ### 9.3 Errori espliciti In caso di input invalido: - exit code non zero; - messaggio chiaro; - nessun output ambiguo. --- ## 10) Documentazione minima richiesta nella skill Per ogni script introdotto devono esistere almeno: 1. una nota in `SKILL.md` o nel workflow che spiega quando usarlo; 2. una mini documentazione locale; 3. almeno 1 smoke test; 4. almeno 1 esempio input/output. ### Esempio di documentazione minima `skills/svg/tools/README.md` Contenuti minimi: - scopo dello script; - parametri supportati; - esempio di comando; - esempio output; - limiti noti; - quando non usarlo. --- ## 11) Esempio concreto: `superellipse.js` ### Scopo Generare in modo deterministico il path SVG di una superellipse/supercerchio, dato un set di parametri. ### Input minimi - `width` - `height` - `n` (esponente) - `samples` ### Output atteso - `path_d` - opzionalmente `svg` - metadati del calcolo ### Perche' e' un buon primo candidato - funzione matematica chiara; - riusabile; - testabile; - nessuna dipendenza esterna necessaria; - evita di far generare al modello path numericamente incoerenti. ### Boundary Lo script **non** deve: - decidere stile o palette; - comporre scene; - ottimizzare automaticamente il path; - sostituire `optimize` o `validate`. Deve solo generare il path. --- ## 12) Pattern d'uso consigliato per l'agente ### Sequenza raccomandata 1. l'agente capisce che il task richiede una shape parametrica precisa; 2. seleziona lo script appropriato; 3. esegue lo script con parametri espliciti; 4. riceve output deterministico; 5. integra il risultato nel workflow SVG; 6. opzionalmente passa il risultato a `validate` / `optimize`. ### Esempio ```text Task: genera un'icona con forma base superellipse 128x128, n=4 -> usa tools/superellipse.js -> integra il path nel markup SVG -> applica validate/optimize ``` --- ## 13) Smoke test minimi richiesti Ogni script deve avere almeno 2 smoke test. ### Per `superellipse.js` #### Smoke 1 - output valido ```bash node skills/svg/tools/superellipse.js --width 100 --height 100 --n 4 --samples 64 ``` Atteso: - `result: ok` - `path_d` non vuoto #### Smoke 2 - input invalido ```bash node skills/svg/tools/superellipse.js --width 100 --height 100 --n 0 --samples 64 ``` Atteso: - exit code errore - messaggio esplicito su parametro non valido ### Smoke 3 - stabilita' opzionale Eseguire due volte lo stesso comando e verificare output identico. --- ## 14) Rischi ### 14.1 Proliferazione incontrollata di utility Rischio: aggiungere molti piccoli script senza governance. Mitigazione: - allow-list di script approvati; - review obbligatoria; - catalogo dei tool locali. ### 14.2 Confusione tra skill e runtime Rischio: l'agente inizia a dipendere da script non documentati o non testati. Mitigazione: - tutti gli script devono essere referenziati esplicitamente nella skill. ### 14.3 Script troppo ampi Rischio: utility che diventano mini-framework. Mitigazione: - perimetro stretto; - un problema per script; - no dipendenze pesanti. ### 14.4 Mancanza di fallback Rischio: l'agente assume esecuzione script sempre disponibile. Mitigazione: - fallback documentale obbligatorio; - messaggi di limite espliciti. --- ## 15) Decisione raccomandata ### Decisione **Approvare l'introduzione di script Node locali nella skill SVG solo per primitive matematiche/geometriche deterministicamente verificabili.** ### Primo candidato raccomandato - `skills/svg/tools/superellipse.js` ### Policy minima - zero dipendenze esterne, salvo eccezioni fortemente motivate; - input/output CLI chiari; - smoke test minimi; - documentazione locale; - integrazione esplicita nel workflow skill; - fallback esplicito se non eseguibile. --- ## 16) Rollout operativo Ordine consigliato per un rollout conservativo: 1. introdurre un solo script pilota (`superellipse.js`); 2. documentarlo in `skills/svg/tools/README.md`; 3. aggiungere 2-3 smoke test; 4. aggiornare `SKILL.md` con regola chiara su quando usarlo; 5. validare se il pattern migliora davvero affidabilita' e riuso; 6. solo dopo, valutare eventuali altri script geometrici. ### Stato implementazione (rollout Fase 3 helper) L'implementazione corrente ha esteso il pilot iniziale in una suite piccola di helper geometrici deterministici, tutti collocati in `skills/svg/tools/`: - `skills/svg/tools/superellipse.js` - `skills/svg/tools/arc-points.js` - `skills/svg/tools/polar-distribute.js` - `skills/svg/tools/bezier-handles.js` - `skills/svg/tools/fit-viewbox.js` - `skills/svg/tools/rounded-corners.js` - `skills/svg/tools/README.md` - smoke dedicato al primo helper: `scripts/smoke-svg-superellipse.js` - smoke aggregato della suite helper: `scripts/smoke-svg-phase3-helpers.js` Questa estensione resta coerente con il pattern target della Fase 3 perche' gli helper sono primitive locali a perimetro stretto, senza dipendenze esterne e con output machine-readable. La promozione resta condizionata a mantenere la suite come supporto numerico della skill, non come framework di generazione grafica. - helper deterministico locale; - contratto CLI esplicito; - output machine-readable; - validazione smoke su caso valido e input invalido per ogni helper; - check di stabilita' deterministica dove utile (`superellipse`). --- ## 16-bis) Integrazione nella roadmap multi-fase Questa analisi viene integrata nella roadmap operativa con il seguente mapping: - Fase 3 (introduzione adesso): - helper deterministici matematico-geometrici a perimetro stretto; - priorita' iniziale `superellipse`, poi `arc-points`/`polar-distribute` e helper di fit/handle. - Fase 4 (dopo pilot tooling): - funzioni di indicizzazione/discovery locale asset; - controllo licenze, path, coerenza metadata e submodule. - Fase 5 (solo con evidenza forte): - funzioni compositive/illustrative complete e orchestrazione multi-step. Regola permanente: - non anticipare in Fase 3 funzioni che dipendono da asset library estese; - mantenere la skill SVG come control plane e gli script come execution helper. --- ## 17) Conclusione L'introduzione di script Node locali nella skill SVG **ha senso** quando questi script: - risolvono problemi numerici o geometrici precisi; - migliorano affidabilita' e ripetibilita'; - restano piccoli, self-contained e testabili; - non spostano la skill da orchestrazione a code-heavy runtime. Per questo motivo, funzioni come il **supercerchio / superellipse** sono un caso d'uso ad alta priorita' e basso rischio per un primo pilot.