--- name: "dev-validate-specs" description: "Wrapper conversazionale per validate-spec-standards.ts. Verifica che i file specs/ rispettino gli Spec Standards v0.17 (frontmatter YAML v2, Gherkin italiano, Mermaid C4, ADR Nygard, Conventional Commits). Output friendly con suggerimenti specifici per ogni problema trovato. Usa quando l'utente dice 'valida le spec', 'controlla gli standard', 'check spec', 'validate specs', 'verifica spec standards', oppure prima di un PR/review per assicurarsi che tutto sia conforme." --- # /dev-validate-specs — Spec Standards Validator (v0.17.0) Wrapper conversazionale su `validate-spec-standards.ts`. Esegue la validazione degli Spec Standards v0.17 sulla directory `specs/` del progetto corrente e presenta i risultati in modo leggibile con suggerimenti azionabili per ogni problema. **Script sottostante**: `dev-methodology/scripts/validate-spec-standards.ts` **Comportamento script-non-trovato**: mostra messaggio `validate-spec-standards.ts non trovato. Esegui bash install.sh --update per aggiornare il plugin.` --- ## Modalità | Flag | Comportamento | |------|---------------| | _(default)_ | Valida `specs/` con output conversazionale friendly | | `--strict` | Passa `--strict` allo script: promuove WARN → ERROR. Indica `in strict mode: N warning trattati come errori` | | `--only CATEGORIA` | Valida solo una categoria (frontmatter\|gherkin\|mermaid\|adr\|commits\|features) | | `--specs-dir PATH` | Specifica directory specs/ alternativa (default: `specs/`) | | `--json` | Passa output JSON raw dello script (utile per CI) | | `--dry-run` | Mostra il comando che verrebbe eseguito senza eseguirlo | --- ## Workflow ### Step 1 — Verifica esistenza dello script Prima di qualsiasi altra operazione, verifica che lo script sottostante esista: ```bash # Path relativo alla root del plugin (da trovare via Glob o path calcolato) SCRIPT_PATH="dev-methodology/scripts/validate-spec-standards.ts" ``` Se il file **non esiste**: ``` validate-spec-standards.ts non trovato. Esegui bash install.sh --update per aggiornare il plugin. ``` Termina qui. Non procedere con altri step. ### Step 2 — Determina parametri Raccogli i flag passati dall'utente: - `--strict` → aggiungi `--strict` al comando - `--only CATEGORIA` → aggiungi `--only CATEGORIA` - `--specs-dir PATH` → aggiungi `--specs-dir PATH` (default `specs/`) - `--json` → passa `--json` per output raw JSON - `--dry-run` → mostra il comando e termina Se in modalità `--strict`, prepara il prefisso del messaggio: `in strict mode: N warning trattati come errori` (N sarà calcolato dopo). ### Step 3 — Esegui lo script Invoca lo script con `npx tsx`: ```bash npx tsx dev-methodology/scripts/validate-spec-standards.ts \ --specs-dir specs/ \ [--strict] \ [--only CATEGORIA] \ [--json] ``` Cattura stdout, stderr e exit code. **Exit codes attesi**: - `0` — tutto OK (o solo warning senza `--strict`) - `1` — almeno 1 errore (o warning con `--strict`) - `2` — errore interno script ### Step 4 — Presenta output conversazionale NON mostrare lo stdout raw. Invece, interpreta i risultati e presenta in modo friendly. #### Se exit code 0 e nessun problema ``` Tutto conforme agli Spec Standards v0.17. N file controllati. Nessun errore, nessun warning. ``` #### Se ci sono problemi Raggruppa per categoria e per severità. Per ogni problema, mostra: 1. Il file e riga coinvolta 2. Il messaggio in italiano 3. Il suggerimento concreto per risolverlo Esempio di output: ``` Trovati N problemi in M file (X errori, Y warning, Z info) Errori da risolvere obbligatoriamente: specs/03-user-stories.md:1 → MISSING_FRONTMATTER: nessun frontmatter YAML trovato → Come risolvere: aggiungi il blocco frontmatter v2 in cima al file: --- spec_version: "2.0" spec_type: "user-stories" ... --- specs/features/sprint-1/US-001.feature:23 → GHERKIN_MISSING_AC_TAG: scenario senza @AC-NNN (riga 23) → Come risolvere: aggiungi @AC-001 sulla riga prima dello Scenario Warning (non bloccanti, ma consigliati): specs/04-tech-spec.md → MERMAID_MISSING_DIAGRAM: nessun diagramma Mermaid trovato in tech-spec → Come risolvere: aggiungi un diagramma C4Context o flowchart Info: . → TOOL_MISSING_CUCUMBER: @cucumber/gherkin non trovato → Come abilitare: bash install.sh --standards Prossimi passi: 1. Risolvi gli N errori obbligatori prima del merge/review 2. Per migrare file v1 → v2 automaticamente: npx tsx dev-methodology/scripts/migrate-specs-v1-to-v2.ts --dry-run 3. Per ri-validare dopo le correzioni: /dev-validate-specs ``` #### Se modalità `--strict` con warning presenti Subito dopo il summary generale, aggiungi una riga: ``` in strict mode: N warning trattati come errori ``` Dove N è il numero di warning che in modalità normale sarebbero warning (ora promossi a errori). #### Se exit code 2 (errore interno) ``` Errore interno nello script validate-spec-standards.ts. Dettaglio: Per diagnosticare: npx tsx dev-methodology/scripts/validate-spec-standards.ts --specs-dir specs/ ``` ### Step 5 — Suggerimenti specifici per codice errore Per i codici di errore più comuni, aggiungi suggerimenti mirati oltre a quello generico del `fix`: | Codice | Suggerimento aggiuntivo | |--------|------------------------| | `LEGACY_V1_FORMAT` | Usa `/dev-adr` per i nuovi ADR. Migra con `migrate-specs-v1-to-v2.ts` | | `MISSING_FRONTMATTER` | Usa `/dev-gherkin-help` per esempi di frontmatter corretto | | `GHERKIN_MISSING_AC_TAG` | Ogni scenario deve avere `@AC-NNN` prima del `Scenario:` | | `ADR_DIR_MISSING` | Crea `specs/adr/` con `/dev-adr init` | | `COMMIT_NOT_CONVENTIONAL` | Formato: `tipo(scope)?: descrizione` — es. `feat(auth): aggiungi JWT` | | `MERMAID_MISSING_DIAGRAM` | Aggiungi diagramma C4 in `04-tech-spec.md` con `/dev-spec --add-diagram` | --- ## Esempi ### Esempio 1 — specs/ conforme ``` User: /dev-validate-specs Skill: → Trova lo script validate-spec-standards.ts → Esegue: npx tsx dev-methodology/scripts/validate-spec-standards.ts --specs-dir specs/ → Exit code: 0 Output: Tutto conforme agli Spec Standards v0.17. 12 file controllati. Nessun errore, nessun warning. ``` ### Esempio 2 — strict mode con warning ``` User: /dev-validate-specs --strict Skill: → Esegue: npx tsx ... --strict → Exit code: 1 (3 warning diventati errori) Output: in strict mode: 3 warning trattati come errori Trovati 3 problemi in 2 file (3 errori, 0 warning, 0 info) Errori da risolvere obbligatoriamente: specs/02-prd.md → MISSING_LAST_UPDATED (⚠️ warning promosso a errore in --strict mode) → Come risolvere: aggiungi last_updated: "2026-05-15T00:00:00Z" ... ``` ### Esempio 3 — script non trovato ``` User: /dev-validate-specs Skill: → Cerca dev-methodology/scripts/validate-spec-standards.ts → File non trovato Output: validate-spec-standards.ts non trovato. Esegui bash install.sh --update per aggiornare il plugin. ``` ### Esempio 4 — solo categoria frontmatter ``` User: /dev-validate-specs --only frontmatter Skill: → Esegue: npx tsx ... --only frontmatter → Mostra solo problemi frontmatter YAML Output: Verifica frontmatter su 8 file specs/ Warning: specs/01-vision.md → MISSING_STATUS: manca status nel frontmatter → Come risolvere: aggiungi status: "draft" 1 warning su 8 file. Nessun errore bloccante. ``` --- ## Integrazione con altre skill - **`/dev-adr`** — crea/aggiorna ADR Nygard (risolve `ADR_DIR_MISSING`, `ADR_MISSING_FRONTMATTER`) - **`/dev-gherkin-help`** — esempi canonici Gherkin italiano (risolve `GHERKIN_MISSING_AC_TAG`, `GHERKIN_MISSING_LANGUAGE`) - **`migrate-specs-v1-to-v2.ts`** — migrazione automatica file v1 → v2 (risolve `LEGACY_V1_FORMAT`, `MISSING_FRONTMATTER` in batch) --- ## Riferimenti - Script: `dev-methodology/scripts/validate-spec-standards.ts` - Migration tool: `dev-methodology/scripts/migrate-specs-v1-to-v2.ts` - Standard guide: `dev-methodology/skills/dev-methodology/references/standards-guide.md` (v0.17.0+) - Skill correlate: `/dev-adr`, `/dev-gherkin-help` - Skill invocanti: `/dev-orchestrate` (quality gate post-Phase 4), `/dev-spec` (pre-output check)