# Sophia Code Reviewer GPT Guida di manutenzione e pubblicazione della configurazione versionata del GPT personalizzato `Sophia Code Reviewer`. Non e un'istruzione runtime e resta nel repository: non caricarlo come Knowledge. Le regole vincolanti per chi modifica questa directory sono in [RULES.md](RULES.md). ## Scopo e sorgente canonica La skill canonica e `skills/mcp-code-reviewer/`. Questa directory ne contiene una copia adattata per GPT Builder: la Knowledge e incorporata, read-only e fail-closed, con link allo stesso livello e senza dipendenze operative da GitHub, altre skill, server MCP, sidecar, sub-agent o orchestratori. La copia puo divergere intenzionalmente dalla sorgente. Non sovrascriverla ciecamente: conserva gli adattamenti GPT, in particolare i limiti di evidenza e gli handoff non operativi. Web Search e Code Interpreter & Data Analysis sono capability opzionali di supporto alla review read-only: il web e pubblico, secondario e local-first; Code Interpreter e limitato ad analisi statica o calcolata dei file disponibili. Nessuna capability abilita implementazione, esecuzione del progetto, build, test, debug runtime o intake multi-sorgente. ## Struttura ```text gpts/sophia-code-reviewer/ |- README.md # guida repository, non Knowledge |- RULES.md # vincoli di manutenzione |- istruzioni.md # campo Instructions `- knowledge/ # file da caricare come Knowledge |- SKILL.md |- project-rules-discovery.md |- review-workflow.md |- functional-consistency.md |- domain-specific-local-rules.md |- evidence-and-severity.md |- output-modes.md `- routing-and-escalation.md ``` ## Mapping GPT Builder | Repository | Destinazione GPT Builder | | --- | --- | | `README.md` — sezione `Configurazione GPT Builder` | nome, descrizione e spunti di conversazione | | `istruzioni.md` | campo **Instructions** | | `knowledge/*.md` | sezione **Knowledge** | | `README.md`, `RULES.md` | solo repository; non caricarli | Il README resta repository-only: non caricarlo come Knowledge né copiarlo nelle Instructions. Copia manualmente nome, descrizione e spunti nei rispettivi campi del GPT Builder. ## Sincronizzazione manuale Quando cambia funzionalmente `skills/mcp-code-reviewer/SKILL.md` o una sua reference: 1. confronta skill/reference sorgente e file corrispondente in `knowledge/`; 2. valuta se la modifica e applicabile al GPT Builder; 3. aggiorna manualmente la copia, preservando gli adattamenti GPT; 4. verifica link, bootstrap e inventario; 5. carica nel GPT Builder; 6. esegui gli smoke test. Per aggiunte o rimozioni Knowledge aggiorna insieme struttura, bootstrap in `istruzioni.md`, inventario `knowledge/SKILL.md` e questa guida. ## Configurazione GPT Builder Questa sezione versiona i metadati da configurare manualmente nel GPT Builder. Non è Knowledge e non deve essere copiata nelle Instructions. ### Nome Sophia Code Reviewer ### Descrizione Esegue review read-only di PR, branch, commit, diff, file e snippet, con finding verificabili su correctness, regressioni e test gap. Per PR, branch, commit o diff servono repository target, oggetto e base; per spec-compliance anche un ticket, requisito o analisi tecnica verificabile. ### Spunti di conversazione * Guidami nell’avvio di una review generale raccogliendo repository target, oggetto, base e scope. * Guidami nell’avvio di una spec-compliance raccogliendo repository target, oggetto, base e una fonte funzionale verificabile. ## Contratti di output e quality gate La skill canonica usa `fix-ready` come default e `human-review` solo esplicito; non include l'output del GPT. Il GPT usa `analyst-handoff` come default e `human-review` solo esplicito. Entrambi accettano zero finding, scelgono inline o documento Markdown in base alla complessita e applicano un quality gate a singola iterazione con eventuale controllo del solo delta. La copia GPT conserva l'adattamento intenzionale dell'handoff per Sophia Technical Analyst: non genera il prompt finale per l'agente di implementazione e non modifica Technical Analyst. ## Budget Instructions `istruzioni.md` ha un hard limit di **8.000 caratteri**, spazi, ritorni a capo e markup inclusi; il target operativo e 7.000-7.500. Un superamento e una verifica fallita: sposta workflow, esempi e template nella Knowledge. Verifica anche il limite effettivo nel GPT Builder prima della pubblicazione. ## Pubblicazione 1. Completa sincronizzazione, verifiche locali e controllo di inventario/link della Knowledge. 2. Aggiorna nome, descrizione e spunti dalla sezione `Configurazione GPT Builder`. 3. Conta i caratteri di `istruzioni.md` (massimo 8.000). 4. Copia `istruzioni.md` nel campo Instructions. 5. Carica tutti e soli i file `knowledge/*.md` elencati sopra. 6. Mantieni abilitate **Web Search** e **Code Interpreter & Data Analysis** nel GPT Builder. 7. Salva o aggiorna il GPT. 8. Esegui gli smoke test manuali. ## Smoke test manuali 1. Instructions senza bootstrap GitHub. 2. Tutti i link di `knowledge/SKILL.md` risolvono file esistenti. 3. Review snippet senza repository, quando consentita dal preflight corrente. 4. Review branch o PR con base di confronto disponibile. 5. Review tecnica senza fonte funzionale: procede nel perimetro tecnico e dichiara il limite. 6. `spec-compliance` senza fonte funzionale: fail-closed. 7. Oggetto della review non accessibile: fail-closed. 8. Nessuna azione di scrittura su repository, PR o ticket. 9. Nessuna dipendenza operativa da skill esterne. 10. `istruzioni.md` entro 8.000 caratteri. 11. I comportamenti invarianti restano equivalenti allo stato precedente: read-only, fail-closed, priorita delle fonti e delle regole locali, limiti dell'evidenza e regole di spec-compliance. Le differenze nei contratti di output sono quelle intenzionalmente documentate: `fix-ready` nella skill e `analyst-handoff` nel GPT. 12. Zero finding restituisce output inline senza piano artificiale. 13. Il quality gate viene eseguito una volta; un'eventuale verifica successiva e solo del delta. 14. Skill `fix-ready` e GPT `analyst-handoff` mantengono i rispettivi default. 15. Fonti locali sufficienti: la review non usa il web. 16. Documentazione versionata necessaria: usa fonte ufficiale citata. 17. Repository o base mancanti: il web non compensa il fail-closed. 18. Best practice online: non diventa automaticamente `project_rule`. 19. Versione non nota: registra limite o `UNCLEAR`; conflitto web/regola locale esplicitato. 20. JSON/YAML o report coverage/benchmark: analisi statica o calcolata con metodo e limiti. 21. Script, binario, build o test richiesti nel sandbox: non vengono eseguiti come prova del runtime target. 22. Artefatto derivato nel sandbox: non viene scritto nel repository; risultato classificato come evidenza calcolata, non runtime. 23. Segreti o PII: redatti o esclusi. 24. Quality gate: controlla uso e tracciabilita degli strumenti una sola volta. 25. Spunto review generale: restituisce un modello compilabile con `Repository target`, `Oggetto review`, `Base` e `Scope`; non inventa valori, non interpreta le etichette come input, non avvia la review né produce subito fail-closed. 26. Spunto spec-compliance: restituisce un modello compilabile con `Repository target`, `Oggetto review`, `Base`, `Scope` e `Fonte funzionale primaria`; dichiara questa fonte obbligatoria, non deriva requisiti dal codice e non avvia la review. 27. Dopo la compilazione degli spunti applica normalmente preflight e fail-closed; se gli input restano incompleti usa il messaggio previsto dalle Instructions. 28. Diff JavaScript ordinario: non attiva il lookup CFML solo per l'estensione `.js`. 29. JavaScript integrato con CFML: attiva il lookup CFML quando il diff contiene segnali contestuali verificabili. ## Checklist finale * [ ] La sorgente canonica e stata confrontata con ogni file Knowledge. * [ ] Gli adattamenti GPT sono preservati; nessuna sovrascrittura cieca. * [ ] I link di `knowledge/SKILL.md` esistono e non contengono `references/`. * [ ] Bootstrap, struttura, mapping e inventario corrispondono ai file reali. * [ ] Instructions entro 8.000 caratteri. * [ ] Il quality gate e integrato nel workflow e nel relativo bootstrap. * [ ] Default, selezione inline/Markdown e zero finding rispettano il contratto skill/GPT. * [ ] Web Search e Code Interpreter & Data Analysis sono abilitati manualmente nel GPT Builder. * [ ] Fonti web e risultati calcolati rispettano tracciabilita, limiti e classificazione dell'evidenza. * [ ] Nome, descrizione e spunti corrispondono alla sezione `Configurazione GPT Builder`. * [ ] Gli spunti avviano la raccolta guidata degli input e non una review con placeholder fittizi. * [ ] Tutti e soli i file Knowledge sono caricati nel GPT Builder. * [ ] Gli smoke test manuali sono completati.