--- name: sts-spec-driven description: "STS Lab Srl — Spec-Driven Reader. Legge e SCRIVE la documentazione spec-driven di un progetto (cartella docs/ con PROJECT_MEMORY, REQUIREMENTS REQ-*, specifiche SPEC-*, task T-*, decisioni D-*, difetti DIF-*, TRACEABILITY, TODO, DECISIONS, CHANGELOG, DEVELOPMENT_LOG). Lettura: trasforma la documentazione in un brief di implementazione prima del codice e chiude il ciclo dopo. Scrittura: se il progetto non ha documentazione la crea da zero facendo scegliere fra layout strutturato (00-INDEX + 01-product…08-project) e piatto, con modelli, intervista e controllo di coerenza; aggiunge nuove spec, requisiti e decisioni a una documentazione esistente. Usala all'inizio di ogni sessione di sviluppo, quando l'utente cita un ID (REQ-, SPEC-, T-, D-, DIF-), chiede di implementare una spec o un task, chiede «leggi la documentazione», «da dove riprendo», «che stato ha il progetto», «crea la documentazione», «imposta lo spec driven», «scrivi la spec di …», «nuovo progetto», o quando si inizia a sviluppare in un progetto senza docs/." --- # Spec-Driven Reader — STS Lab Srl > **STS Lab Srl** · Skill proprietaria per lo sviluppo software guidato da specifiche. > © 2026 STS Lab Srl — tutti i diritti riservati. Nei progetti STS Lab la documentazione **precede** il codice e ne è il contratto: ``` REQ-xxx cosa deve fare il prodotto (REQUIREMENTS) ▼ SPEC-xxx come lo fa: API, dati, regole, (03-specs/ o documenti di modulo) │ errori, criteri di accettazione ▼ T-xxx unità di lavoro implementabile (TODO) ▼ codice + test ▼ TRACEABILITY chiude il cerchio: ogni REQ ha spec, task e test che passano ``` Ogni scelta strutturale è una decisione numerata `D-xxx`; ogni difetto noto è un `DIF-xx`. Questa skill serve a **scrivere** quella catena quando manca, a **leggerla bene** prima di toccare il codice, e a **richiuderla** dopo. ### Quale modalità | Situazione | Modalità | Dove | |---|---|---| | Il progetto **non ha** documentazione spec-driven (o l'utente chiede di crearla) | **Scrittura** | §A qui sotto + [references/scrittura.md](references/scrittura.md) | | C'è solo lo scheletro, con molti `DA COMPILARE` | **Scrittura** (completamento) | idem, dallo step in corso | | Serve una spec, un requisito o una decisione **nuovi** | **Scrittura** (aggiunta) | [references/scrittura.md](references/scrittura.md) §6 | | La documentazione c'è e si deve sviluppare | **Lettura** | §1–§8 | --- ## 0. Strumento: `scripts/spec_index.py` Libreria standard Python 3.8+. Usalo **prima** di aprire i file grandi: DECISIONS e DEVELOPMENT_LOG possono superare le 3–6 000 righe e non vanno mai letti interi. ```bash S=~/.claude/skills/sts-spec-driven/scripts/spec_index.py # lettura (non scrive nulla) python $S overview # layout, documenti chiave, stato delle spec, segnaposto python $S context SPEC-004 # definizione + ID collegati + TODO + TRACEABILITY python $S find D-014 # dove è definito e chi lo cita python $S check # coerenza: orfani, requisiti scoperti, derive di stato python $S next-id SPEC|D|DIF|T|REQ [--area AUT] [--spec SPEC-004] [--prefisso W] # scrittura (non sovrascrive mai un file esistente) python $S scaffold --layout strutturato|piatto --progetto "Nome" python $S new-spec --titolo "Titolo" [--prefisso W (solo layout piatto)] ``` Su Windows da PowerShell il `~` non viene espanso: usa `$HOME\.claude\skills\sts-spec-driven\scripts\spec_index.py` (oppure lancialo dal tool Bash, dove `~` funziona). - Per una SPEC, `context` stampa l'indice delle sezioni con i numeri di riga: leggi poi solo le sezioni che servono con `Read offset/limit`. - `check` esce con codice 1 se trova problemi; riporta all'utente cosa ha trovato. Se Python non c'è, ripiega su `Grep` con il pattern `REQ-[A-Z]+-\d+|SPEC-\d{3}|T-[A-Z]{0,2}\d+|D-\d{3}|DIF-\d+` e copia a mano i modelli da `templates/`. --- ## A. Scrittura — creare la documentazione Procedura completa in [references/scrittura.md](references/scrittura.md). In sintesi: 1. **Verifica** che non esista già (§1). Se esiste solo in parte, non ricrearla: completala. 2. **Fai scegliere il layout all'utente** con `AskUserQuestion`, mettendo per primo con «(Consigliato)» quello adatto — *Strutturato* per progetti con più moduli, integrazioni, riscritture, committente esterno; *Piatto* per progetti piccoli, prototipi, un solo modulo. Chiedi anche dove crearla (default `docs/` alla radice del repository). 3. **Crea lo scheletro** con `scaffold`. I modelli stanno in `templates/strutturato/`, `templates/piatto/`, `templates/spec.md`, `templates/modulo.md`. 4. **Raccogli le informazioni**: prima leggi README, manifest, codice; poi intervista l'utente (al massimo 4 domande per giro, solo ciò che manca). Se c'è codice senza documenti, ricostruisci i requisiti dal codice come tipo **P** con *Origine* `file:funzione`. 5. **Scrivi nell'ordine degli step** (visione → requisiti → architettura → spec → contratto e dati → devops → qualità e backlog), con un riepilogo e la conferma dell'utente a fine step. 6. **Nuove spec** con `new-spec`: numerazione, blocco di task e lettera dei criteri sono automatici. Nascono sempre «da approvare». 7. **Chiudi** con `check` e riporta l'esito. Regole che non si derogano: - **Non inventare**: ciò che non è noto resta `DA COMPILARE` o diventa una domanda. - **Mai approvare da solo**: una spec diventa *Approvata* solo dopo un sì esplicito dell'utente (procedura in scrittura.md §5). - **Mai sovrascrivere** documenti esistenti; i contenuti sparsi si spostano nei documenti giusti, con l'accordo dell'utente. --- ## 1. Trovare la documentazione Cerca nell'ordine: `docs/`, `src/docs/`, `*/src/docs/`, `documentation/`. Una cartella è spec-driven se contiene almeno `PROJECT_MEMORY.md` o `00-INDEX.md` più uno fra `DECISIONS.md`, `TODO.md`, `REQUIREMENTS.md`. Leggi anche `CLAUDE.md`/`README.md` alla radice del repository: possono indicare la cartella o regole locali. **Se non la trovi**, non scrivere codice: di' all'utente che il progetto non ha documentazione spec-driven e proponi di crearla (§A). Se l'utente preferisce procedere senza, rispetta la scelta e annotala nella risposta. Due layout ricorrenti (dettagli in [references/layout.md](references/layout.md)): | Layout | Riconoscimento | Esempio | |---|---|---| | **Strutturato** | cartelle `01-product/ … 08-project/`, `00-INDEX.md`, `03-specs/SPEC-xxx-*.md` | `KadeonCad_v2/docs` | | **Piatto** | tutti i `.md` in una cartella, specifiche come documenti di modulo (`CAD_MODULE.md`, `whatsapp/DESIGN.md`) | `Kadeon/kadeon/src/docs` | --- ## 2. Lettura di inizio sessione (sempre, prima del codice) 1. **`overview`** con lo script. 2. **`PROJECT_MEMORY.md`** — per intero. Contiene ciò che non è deducibile dal codice e che, se dimenticato, fa ripetere errori: vincoli non negoziabili, azioni pendenti di sicurezza, «le cose da non dimenticare mai». Tienile presenti per tutta la sessione. 3. **`00-INDEX.md`** (layout strutturato) — tabella degli step, stato dell'implementazione e i riquadri `> **Titolo (data):**` in testa: sono le novità più recenti, in ordine inverso. 4. **Indice di `DECISIONS.md`** — solo la tabella iniziale; le singole decisioni si leggono quando servono. 5. **`TODO.md`** — sezione «fuori sequenza / prima di tutto» e la fase corrente. Non leggere CHANGELOG, DEVELOPMENT_LOG, openapi.yaml per intero: si interrogano per ID o data. --- ## 3. Prima di implementare: il cancello Rispondi a queste domande **prima** di scrivere una riga. Se una risposta è «no», fermati e dillo all'utente. | # | Domanda | Dove si verifica | Se «no» | |:-:|---|---|---| | 1 | Il lavoro richiesto corrisponde a un `T-xxx`? | TODO, sezione *Task* della spec | Proponi il task e la spec di appartenenza | | 2 | Il task appartiene a una `SPEC-xxx` in stato **Approvata**? | riga `Stato:` della spec, 00-INDEX | Non implementare: segnala lo stato (*da approvare*, 🟡) e chiedi | | 3 | Le dipendenze del task (colonna *Dipende da*) sono ✅? | TODO, tabella task della spec | Segnala l'ordine corretto | | 4 | Nessuna decisione `D-xxx` **accettata** lo vieta o lo vincola diversamente? | DECISIONS (per ID), PROJECT_MEMORY | Cita la decisione; una deviazione richiede una nuova `D-xxx` | | 5 | Se tocca un requisito di **parità** (tipo `P`) cambia il comportamento? | REQUIREMENTS, colonna *Tipo* | È una decisione di prodotto: serve una `D-xxx` | | 6 | Contratto API e schema dati sono già scritti? | `openapi.yaml` / API.md, DATABASE.md | Si scrive prima il contratto (contract-first) | Eccezione legittima: richiesta esplicita dell'utente di procedere comunque. In quel caso procedi, ma registra la deviazione (vedi §6) — è ciò che i progetti chiamano «inversione» e che va lasciata scritta. --- ## 4. Leggere una spec Struttura tipica di una `SPEC-xxx` (le sezioni possono variare): 1. Intestazione: `Stato`, versione, data, **requisiti coperti**, decisione di riferimento. 2. Contesto e obiettivo — il *perché*; spesso contiene un dato misurato che giustifica la scelta. 3. «Cosa cambia rispetto a ciò che è già scritto» — elenco dei punti fermi che la spec modifica. 4. Regole / algoritmo in **forma normativa**: le parole in grassetto e i «**non**» sono vincoli. 5. Contratto API: rotta, ingresso, uscita, **tabella degli esiti con codici HTTP**. 6. Errori. 7. **Criteri di accettazione** (`D1…D12`, `P1…P24`, …): ognuno diventa almeno un test. 8. **Task** con dipendenze. Regole di lettura: - Leggi la spec **intera** quando la implementi; usa l'indice di `context` per le altre. - I paragrafi «è una decisione, non una dimenticanza» descrivono comportamenti voluti che sembrano bug: non «correggerli». - Sezioni con suffisso `bis`/`ter` (es. §5.3bis) sono aggiunte successive: leggile, spesso modificano la regola base. - Per ogni `REQ-` citato leggi la riga in REQUIREMENTS: colonna **Tipo** (P parità / C correzione / N nuovo) e **Origine** (per i `P` la fonte di verità è il codice della versione precedente indicato lì). - Per ogni `D-` citata leggi **solo** la sezione `## D-xxx` (Contesto → Decisione → Alternative → Conseguenze). Una decisione *Superata da D-yyy* non vale più: segui D-yyy. - Il glossario (`GLOSSARY.md`) fissa i termini: usa gli stessi nomi nel codice e nei messaggi. --- ## 5. Il brief di implementazione Prima di scrivere codice, presenta all'utente un brief compatto con il modello in [references/brief-template.md](references/brief-template.md): obiettivo, stato della spec, requisiti, regole normative, contratto, criteri di accettazione → test, task e dipendenze, decisioni vincolanti, file di codice probabilmente toccati, **incoerenze trovate**. Per un task piccolo il brief può stare in poche righe; non saltare mai le sezioni *criteri* e *incoerenze*. --- ## 6. Dopo l'implementazione: chiudere il ciclo Aggiorna la documentazione **nella stessa modifica del codice**, seguendo [references/chiusura-ciclo.md](references/chiusura-ciclo.md). In sintesi: | Documento | Cosa scrivere | Quando | |---|---|---| | TODO | stato del task (⬜ → 🟡 → ✅) | ✅ solo con test passanti | | TRACEABILITY | stato della riga REQ, criteri coperti | **quando il test passa, non quando il codice è scritto** | | spec | nuove sezioni `bis`, criteri e task aggiunti | se la regola cambia o si estende | | DECISIONS | nuova `D-xxx` (mai modificarne una vecchia: la si *supera*) | ogni scelta strutturale o deviazione | | CHANGELOG | cosa cambia **per chi usa il prodotto** | ogni modifica visibile | | DEVELOPMENT_LOG | cosa si è scoperto e **perché** si è deciso così | scoperte, tentativi respinti, misure | | PROJECT_MEMORY | solo ciò che, dimenticato, fa ripetere un errore | raramente | | 00-INDEX | riquadro `> **Titolo (data):**` in testa + date «Ultimo aggiornamento» | ogni consegna rilevante | Riporta sempre il numero di test eseguiti e il loro esito reale (es. «backend 614 (+3)»). Non dichiarare ✅ ciò che non è stato verificato: scrivi 🟡 e cosa manca. --- ## 7. Incoerenze e fonti di verità La documentazione viva va in deriva: indici non aggiornati, totali vecchi, spec marcata «da approvare» ma task già ✅, ID citati e mai definiti (l'`overview` li elenca). Quando le trovi: 1. **Non correggere in silenzio e non sceglierne una a caso.** Elencale nel brief. 2. Applica la gerarchia delle fonti di verità dichiarata dal progetto. Default: - contratto API → `openapi.yaml` (non API.md, non il codice); - requisiti di parità → codice della versione precedente citato in *Origine*; - stato «verificato» → test **eseguiti** (non la TRACEABILITY); - decisioni → l'ultima `D-xxx` accettata che non è superata; - stato di una spec → la sua riga `Stato:`; in assenza, l'indice. 3. Se l'incoerenza blocca il lavoro, chiedi all'utente; altrimenti prosegui e proponi la correzione documentale insieme alla consegna. --- ## 8. Cose da non fare - Implementare da una spec *da approvare* o da un'idea non scritta, senza dirlo. - «Modernizzare» ciò che un requisito di parità o una decisione congela. - Rinumerare o riusare un ID: gli ID sono **immutabili**; quelli eliminati si barrano (`~~T-005~~`). - Cancellare una decisione o una voce di diario: si superano o si annotano. - Leggere per intero file da migliaia di righe quando basta una sezione. - Copiare segreti trovati nella documentazione in risposte, log o commit. --- **STS Lab Srl** · Spec-Driven Reader v1.1 (lettura + scrittura) · 2026-10-16 · uso interno e per i clienti STS Lab Srl