# Analisi tecnica nuova skill `ai-documents-validation` Data: 2026-04-27 Stato: proposta tecnica per implementazione skill ## 1. Sintesi decisionale Creare una skill specialistica repo-specifica per `E:\ai-documents-validation`, dedicata allo sviluppo, estensione, review e pianificazione dei tipi documento supportati dal validatore `docvalidator`. Nome consigliato: `ai-documents-validation-document-type` Collocazione consigliata nel repository MCP: `skills/ai-documents-validation-document-type/` La skill non deve essere una skill generica sull'uso dell'AI nei programmi. Il documento sorgente principale (`guida_sviluppo_nuovo_tipo_documento.md`) descrive un workflow applicativo molto vincolato: classificazione documentale, parser campi con diagnostica, reliability, regole business, superfici API/CLI, test e documentazione pubblica. Una skill generica avrebbe trigger troppo ampio e sovrapposizione con `mcp-technical-analyst`, `mcp-master-orchestrator` e skill specialistiche esistenti. ## 2. Fonti analizzate ### Evidenze osservate - `E:\ai-documents-validation\AGENTS.md` impone policy docs-first tramite shelf `ai_documents_validation_docs`, con fallback filesystem solo se Docs MCP non e' disponibile o non sufficiente. - `E:\ai-documents-validation\_documentation\guida_sviluppo_nuovo_tipo_documento.md` definisce checklist completa per introdurre nuovi tipi documento. - `E:\ai-documents-validation\README.md` descrive il progetto come pre-validatore documenti fornitori per integrazione Giie, con modelli locali open-weight e output JSON strutturato. - `docs/mcp-skills-agents-development-guide.md` richiede skill snelle, compatibili, con confini chiari e senza refactor fuori scope. - `docs/skill-governance-matrix.md` mostra standard locale: trigger precisi, separazione `SKILL.md` / `references/`, eval coverage e confini con analyst/orchestrator. - `skill-creator` richiede frontmatter con soli `name` e `description`, body conciso, risorse caricate progressivamente, validazione con `quick_validate.py`. ### Inferenze - La skill deve essere procedurale, non enciclopedica: deve guidare un coding agent a non dimenticare parti della pipeline. - Il valore principale non e' spiegare cos'e' l'AI, ma preservare coerenza tra documentazione, codice e test in un repo dove ogni nuovo tipo documento tocca molte superfici. - La skill deve incorporare il routing Docs MCP-first per rispettare `AGENTS.md` del repo target. ### Punti aperti - Il path canonico indicato da `AGENTS.md` e' `S:\ai_projects\ai_documents_validation`, mentre la copia osservata e' `E:\ai-documents-validation`. La skill deve supportare entrambi, dando priorita' al path passato dall'utente o rilevato nel workspace. - Non e' ancora definito se la skill andra' installata solo in questo repo MCP o anche in `$CODEX_HOME/skills`. - Non e' ancora deciso se creare subito eval dedicati; tecnicamente sono consigliati per evitare trigger troppo generici. ## 3. Problema da risolvere Nel repo `ai-documents-validation`, aggiungere un nuovo documento non e' una modifica locale. La guida elenca dipendenze trasversali: - `src/docvalidator/config.py` per costanti e `REFERENCE_TEXTS`; - `src/docvalidator/field_extraction/.py` per parser; - `src/docvalidator/field_extraction/__init__.py` per routing; - `src/docvalidator/rules.py` per regole KO/WARNING; - `src/docvalidator/reliability.py` per campi obbligatori e segnali trasversali; - `src/docvalidator/api/catalog.py` e test catalogo; - `src/docvalidator/cli.py`; - API validate e schema; - `README.md` e documentazione sotto `_documentation/`; - test parser, regole, reliability, API e pipeline. Senza skill, un agente rischia di applicare anti-pattern esplicitamente vietati: - aggiungere solo `REFERENCE_TEXTS`; - creare parser senza diagnostica completa; - omettere chiavi per campi mancanti; - produrre date non ISO; - aggiornare API catalog senza test e README; - duplicare warning tra reliability e regole; - alterare soglie globali per accomodare un singolo documento. ## 4. Scope della nuova skill ### In scope - Aggiunta di un nuovo tipo documento supportato da `docvalidator`. - Estensione o correzione di parser documentali esistenti. - Review tecnica di modifiche che toccano classificazione, estrazione campi, diagnostica, regole o reliability. - Pianificazione di una nuova integrazione documentale prima del coding. - Verifica che codice, test e documentazione pubblica restino allineati. - Handoff operativo a `mcp-technical-analyst` quando serve ricostruzione multi-sorgente piu' ampia. ### Out of scope - Skill generica su AI, LLM, embedding o OCR. - Debug infrastrutturale generico FastAPI, packaging Python o deployment non legato ai tipi documento. - Automazione Docs MCP generica, che resta competenza di `mcp-docs-navigator`. - Review codice generica, che resta competenza di `mcp-code-reviewer`. - Coordinamento multi-fase ampio, che resta competenza di `mcp-master-orchestrator`. ## 5. Trigger consigliato Frontmatter proposto: ```yaml --- name: ai-documents-validation-document-type description: Develop, extend, plan, or review supported document types in the ai-documents-validation/docvalidator repository. Use when Codex must add a new document type, modify field extraction parsers, align classification REFERENCE_TEXTS, field diagnostics, business rules, reliability, API catalog, CLI, tests, and public documentation for E:\ai-documents-validation or the canonical ai_documents_validation project. --- ``` Caratteristiche del trigger: - Include azioni: develop, extend, plan, review. - Include dominio: supported document types, `docvalidator`. - Include superfici critiche: classification, diagnostics, rules, reliability, API, CLI, tests, docs. - Include path osservato e nome canonico progetto. Anti-trigger da dichiarare nel body: - Se richiesta e' solo review generica di diff senza vincoli funzionali, usare `mcp-code-reviewer`. - Se richiesta parte da ticket/documenti/commit multipli da correlare, usare prima `mcp-technical-analyst`. - Se richiesta e' solo gestione shelf/docs, usare `mcp-docs-navigator`. ## 6. Architettura skill consigliata Struttura proposta: ```text skills/ai-documents-validation-document-type/ ├── SKILL.md ├── references/ │ ├── new-document-type-checklist.md │ ├── docs-first-policy.md │ ├── diagnostic-contract.md │ ├── api-integration.md │ └── test-and-validation.md └── evals/ └── evals.json ``` ### `SKILL.md` Deve restare corto. Contenuti minimi: 1. Scopo e confini. 2. Discovery iniziale: - individuare `project_path`; - leggere `AGENTS.md`; - rispettare Docs MCP-first; - fallback filesystem mirato. 3. Workflow operativo: - leggere guida nuovo tipo documento; - leggere implementazioni esistenti `durc.py`, `identity.py`, `rules.py`, `reliability.py`, `api/catalog.py`; - definire campi, obbligatorieta', regole e testi riferimento; - implementare parser con diagnostica; - allineare router, rules, reliability, API, CLI, docs, test. 4. Stop conditions: - mancano requisiti documento; - conflitto tra guida e codice; - dati sensibili reali non anonimizzati; - dipendenza multi-sorgente ampia. 5. Rimandi alle reference. ### `references/new-document-type-checklist.md` Contiene checklist estesa derivata dalla guida repo: - configurazione documento; - parser campi; - router; - regole; - reliability; - catalogo API; - CLI; - validate API; - documentazione pubblica; - test minimi; - anti-pattern. Questa reference evita di gonfiare `SKILL.md` ma rende disponibile la procedura completa quando il task e' davvero aggiungere un tipo documento. ### `references/docs-first-policy.md` Contiene procedura repo-specifica: - controllare shelf `ai_documents_validation_docs`; - verificare freshness su `README.md` e `_documentation/**/*.md`; - rebuild se shelf assente o potenzialmente stale; - usare `docs_search` e `docs_read_document`; - fallback filesystem solo se MCP non disponibile o incompleto; - supportare path canonico `S:\ai_projects\ai_documents_validation` e path locale `E:\ai-documents-validation`. ### `references/diagnostic-contract.md` Contiene contratto tecnico per `field_diagnostics`: ```python { "value": value, "confidence": 0.0, "sources": [], "support_count": 0, "conflict_count": 0, "status": "missing", } ``` Include stati ammessi: - `confirmed`; - `partial`; - `conflicting`; - `missing`. Include regole: - restituire tutti i campi attesi anche se `None`; - normalizzare date ISO `YYYY-MM-DD`; - usare helper in `field_extraction.utils`; - preferire parser line-aware e OCR-tolerant; - non loggare dati sensibili estratti. ### `references/api-integration.md` Contiene guida operativa per integrare il microservizio FastAPI del repo in un'altra applicazione: - avvio servizio e prerequisiti; - endpoint pubblici; - autenticazione; - CORS; - request multipart; - response contract; - gestione errori; - mapping applicativo dello stato `OK` / `WARNING` / `KO`; - test consumer e Postman/OpenAPI. ### `references/test-and-validation.md` Contiene validazioni consigliate: ```bash pytest tests/test_field_extraction.py tests/test_rules.py tests/test_reliability.py -m "not slow" pytest tests/ -m api pytest tests/ -m "not slow" ``` Include mapping modifica -> test: - parser -> `tests/test_field_extraction.py`; - regole -> `tests/test_rules.py`; - reliability -> `tests/test_reliability.py`; - catalogo API -> `tests/test_api_supported_types.py`; - validate API -> `tests/test_api_validate.py`; - integrazione pipeline -> `tests/test_pipeline.py`; - PDF reali non sensibili -> regression `slow` o smoke script dedicato. ## 7. Workflow operativo atteso ### Fase 1 - Intake 1. Identificare repo target (`project_path`) da prompt o workspace. 2. Leggere `AGENTS.md` del repo target. 3. Verificare docs via Docs MCP secondo policy repo. 4. Leggere guida nuovo tipo documento. 5. Se task e' solo analisi, produrre piano; se task chiede implementazione, procedere. ### Fase 2 - Discovery codice Leggere almeno: - `src/docvalidator/config.py`; - `src/docvalidator/field_extraction/durc.py`; - `src/docvalidator/field_extraction/identity.py`; - `src/docvalidator/field_extraction/__init__.py`; - `src/docvalidator/rules.py`; - `src/docvalidator/reliability.py`; - `src/docvalidator/api/catalog.py`; - `src/docvalidator/cli.py`; - test correlati. ### Fase 3 - Specifica documento Definire prima del coding: - codice interno documento; - marker testuali per classificazione; - campi estratti; - campi obbligatori; - regole KO; - regole WARNING; - regole di scadenza o cronologia; - contesto opzionale API/CLI; - fixtures pulite e rumorose. ### Fase 4 - Implementazione Ordine consigliato: 1. `config.py` e `REFERENCE_TEXTS`. 2. Parser nuovo con funzioni standard. 3. Router in `field_extraction/__init__.py`. 4. Regole business. 5. Reliability. 6. Catalogo API. 7. CLI. 8. Schema/API validate se necessario. 9. Test. 10. Documentazione pubblica. ### Fase 5 - Verifica Eseguire test mirati coerenti con impatto. Se cambia codice server/API, segnalare che puo' servire riavvio del servizio. ## 8. Integrazione API in un'altra applicazione La skill deve coprire anche richieste tipo: ```text Integra l'API di ai-documents-validation nel portale X. ``` Questo scenario e' diverso dall'aggiunta di un nuovo tipo documento: qui il focus e' usare il microservizio `docvalidator` come dipendenza applicativa esterna. La skill deve guidare l'agente a leggere prima `_documentation/guida_deployment_api.md`, `src/docvalidator/api/schemas.py`, `src/docvalidator/api/routers/validate.py` e, se serve, gli asset Postman. ### Contratto HTTP osservato Endpoint disponibili: - `GET /api/v1/health`; - `GET /api/v1/supported-types`; - `POST /api/v1/validate`; - Swagger UI su `/docs`; - OpenAPI JSON su `/openapi.json`. Autenticazione: - se `DOCVALIDATOR_API_KEY` non e' configurata, il servizio gira in dev mode e gli endpoint sono accessibili senza header; - se `DOCVALIDATOR_API_KEY` e' configurata, gli endpoint protetti richiedono `X-API-Key: `. CORS: - se `DOCVALIDATOR_API_CORS_ALLOW_ORIGINS` non e' configurata, CORS resta disabilitato; - se configurata come CSV, abilita solo origini dichiarate ed espone `X-Request-ID`. Request principale: ```http POST /api/v1/validate Content-Type: multipart/form-data X-API-Key: ``` Campi multipart: - `file`: PDF da validare; - `doc_type`: tipo documento atteso, oggi `DURC` o `DOCUMENTO_IDENTITA`; - `context_cf`: opzionale, usato solo per `DURC` come CF/P.IVA atteso. Esempio `curl`: ```bash curl \ -X POST \ -H "X-API-Key: secret-key" \ -F "file=@./durc.pdf;type=application/pdf" \ -F "doc_type=DURC" \ -F "context_cf=03176620601" \ http://localhost:8000/api/v1/validate ``` ### Contratto response da consumare La response `ValidateResponse` include: - `schema_version`; - `doc_type_expected`; - `doc_type_predicted`; - `classification_confidence`; - `document_reliability_score`; - `document_reliability_status`; - `status`; - `issues`; - `extracted_fields`; - `field_diagnostics`; - `llm_message_for_user`; - `metadata`. L'applicazione consumer non deve basarsi solo su `llm_message_for_user`. Deve usare campi machine-readable: - `status` per decisione primaria; - `issues[].code`, `issues[].severity`, `issues[].field` per workflow e UI; - `extracted_fields` per precompilazione o confronto dati; - `field_diagnostics` per spiegare confidenza, conflitti e campi mancanti; - `metadata.text_extraction_method`, `metadata.ocr_used`, `metadata.reliability_signals` per audit tecnico. Mapping consigliato: | `status` | Uso applicativo | | --- | --- | | `OK` | Documento accettabile automaticamente, salvo policy cliente piu' restrittive. | | `WARNING` | Documento leggibile ma richiede verifica o conferma manuale. | | `KO` | Documento non accettabile o input non validabile. Bloccare o richiedere nuovo upload. | ### Error handling La response errore usa envelope: ```json { "error": { "code": "STABLE_CODE", "message": "Human-readable error summary.", "request_id": "correlation-id", "details": {} } } ``` L'app consumer deve: - loggare `request_id` per correlazione; - mostrare messaggi utente propri, non necessariamente `error.message` raw; - gestire almeno `401`, `422`, `500`; - distinguere errori HTTP da `status = "KO"` della validazione, che e' una response applicativa valida. ### Linee guida architetturali per integrazione Integrare come microservizio HTTP separato, non importando direttamente moduli Python nell'app consumer, salvo monorepo controllato e vincolo esplicito. Motivi: - modelli caricati a startup e condivisi in-process; - API gia' stabilizza schema pubblico; - validazione usa executor con `max_workers=1` per evitare contesa sui modelli; - deployment puo' restare su host con GPU/CPU dedicata; - consumer resta disaccoppiato dal ciclo di vita dei modelli. Pattern consigliato lato consumer: 1. All'avvio o periodicamente chiamare `GET /api/v1/health`. 2. Caricare `GET /api/v1/supported-types` per popolare UI e validare `doc_type`. 3. In upload documento, inviare PDF via `POST /api/v1/validate`. 4. Salvare response completa o sottoinsieme auditabile secondo policy privacy. 5. Usare `status` e `issues` per decidere workflow. 6. Esporre all'utente messaggio controllato dall'app, eventualmente arricchito con `llm_message_for_user`. ### Sicurezza e privacy La skill deve ricordare all'agente di verificare: - API key configurata fuori dev; - CORS limitato alle origini reali; - dimensione e numero pagine PDF coerenti con guardrail del servizio; - nessun log applicativo con dati personali estratti; - retention dei PDF e delle response definita dal consumer; - trasporto HTTPS o rete interna protetta in ambienti non locali. ### Impatto dei nuovi tipi documento sull'integrazione Quando la skill aggiunge un nuovo tipo documento, deve aggiornare anche il punto di integrazione: - `SupportedDocType` in `api/schemas.py`, se enum hard-coded; - `SUPPORTED_TYPES_CATALOG` in `api/catalog.py`; - `GET /api/v1/supported-types`; - esempi OpenAPI/Postman se utili; - documentazione consumer se il nuovo tipo richiede campi context aggiuntivi; - test `tests/test_api_supported_types.py` e `tests/test_api_validate.py`. Se il nuovo documento richiede nuovi parametri di contesto oltre `context_cf`, non introdurre campi generici opachi senza motivazione. Preferire contratto esplicito, testato e documentato. ### Test integrazione consumer Minimo consigliato: - smoke `GET /api/v1/health`; - test `GET /api/v1/supported-types` e verifica presenza tipo atteso; - test `POST /api/v1/validate` con PDF valido; - test `POST /api/v1/validate` con `doc_type` errato o mancante; - test auth con API key assente/errata quando `DOCVALIDATOR_API_KEY` e' attiva; - test CORS se consumer e' browser-based. La skill deve indirizzare l'agente a usare OpenAPI/Postman quando l'app consumer non e' Python, e test API repo quando cambia il server: ```bash pytest tests/ -m api ``` ## 9. Confini con skill esistenti | Skill | Relazione | Regola routing | | --- | --- | --- | | `mcp-technical-analyst` | Upstream analitico | Usare prima quando serve correlare ticket, documenti, commit o allegati. | | `mcp-master-orchestrator` | Coordinamento multi-fase | Usare quando ci sono fasi parallele o handoff tra skill multiple. | | `mcp-code-reviewer` | Review generica | Usare per diff/commit/PR non specifici del dominio documentale. | | `mcp-docs-navigator` | Docs MCP specialistico | Usare per manutenzione shelf, tagging o scansione documentale. | | `mcp-office-expert` | Documenti/PDF sorgenti | Usare se bisogna estrarre testo da PDF/DOCX di esempio prima di definire parser. | La nuova skill e' specialistica esecutiva. Non deve diventare orchestrator ne' analyst universale. ## 10. Eval consigliati Creare `evals/evals.json` con casi minimi: 1. Prompt: "Aggiungi supporto al certificato X in `E:\ai-documents-validation`." Atteso: trigger skill, lettura AGENTS, guida nuovo tipo, piano multi-superficie. 2. Prompt: "Modifica solo `REFERENCE_TEXTS` per riconoscere un nuovo documento." Atteso: skill segnala anti-pattern e richiede parser/regole/test/docs. 3. Prompt: "Review diff che aggiunge parser senza field_diagnostics." Atteso: finding bloccante sul contratto diagnostico. 4. Prompt: "Indicizza la documentazione del progetto." Atteso: non usare questa skill come primaria; routing a `mcp-docs-navigator`. 5. Prompt: "Ricostruisci da ticket e commit perche' il nuovo documento fallisce in QA." Atteso: routing primario a `mcp-technical-analyst`, possibile uso successivo della skill. 6. Prompt: "Aggiungi nuovo tipo documento ma non aggiornare README." Atteso: skill rifiuta omissione come done incompleto, salvo istruzione esplicita e rischio documentato. 7. Prompt: "Integra l'API del validatore in un portale esterno." Atteso: skill usa guida deployment API, espone endpoint/auth/CORS/request/response/error handling e distingue `KO` applicativo da errore HTTP. 8. Prompt: "Aggiungi nuovo tipo documento e rendilo disponibile all'app consumer." Atteso: skill aggiorna enum/schema, catalogo, supported-types, test API e documentazione integrazione. ## 11. Rischi e mitigazioni ### Rischio: trigger troppo ampio Mitigazione: - descrizione frontmatter focalizzata su `ai-documents-validation/docvalidator`; - anti-trigger nel body; - eval di routing negativo. ### Rischio: duplicazione documentazione repo Mitigazione: - `SKILL.md` breve; - checklist dettagliata in `references/`; - fonte canonica resta `E:\ai-documents-validation\_documentation\guida_sviluppo_nuovo_tipo_documento.md`; - reference skill deve riassumere il workflow, non sostituire la guida viva. ### Rischio: path hard-coded Mitigazione: - accettare `project_path` dal prompt; - rilevare workspace corrente; - supportare sia `S:\ai_projects\ai_documents_validation` sia `E:\ai-documents-validation`; - non assumere che Docs MCP abbia sempre path locale identico. ### Rischio: agenti saltano Docs MCP-first Mitigazione: - inserire procedura docs-first nel primo blocco operativo della skill; - reference dedicata `docs-first-policy.md`; - eval che controlla menzione della shelf `ai_documents_validation_docs`. ### Rischio: skill diventa troppo lunga Mitigazione: - tenere `SKILL.md` sotto 150-200 righe; - spostare contratti e checklist in `references/`; - non includere README, quick reference o changelog extra nella skill. ### Rischio: integrazione API incompleta Mitigazione: - reference dedicata `api-integration.md`; - includere health, supported-types, validate, auth, CORS, response contract ed error envelope; - distinguere validazione `KO` da errori HTTP; - richiedere test consumer minimi e `pytest tests/ -m api` quando cambia server. ## 12. Piano implementativo consigliato ### Step 1 - Scaffold Usare `skill-creator`: ```bash scripts/init_skill.py ai-documents-validation-document-type --path skills --resources references ``` Se `init_skill.py` non e' disponibile nel repo corrente, creare manualmente struttura minima rispettando frontmatter e poi validare con script disponibile in `$CODEX_HOME`. ### Step 2 - Redazione risorse Creare: - `SKILL.md`; - `references/new-document-type-checklist.md`; - `references/docs-first-policy.md`; - `references/diagnostic-contract.md`; - `references/api-integration.md`; - `references/test-and-validation.md`. ### Step 3 - Eval Aggiungere eval di routing e anti-pattern. Priorita' alta perche' la skill e' repo-specifica ma vive in ecosistema con molte skill sovrapposte. ### Step 4 - Validazione Usare Node per gli smoke/schema check locali, in coerenza con il toolchain principale del repo MCP: ```bash node -e "const fs=require('fs'); const s=fs.readFileSync('skills/ai-documents-validation-document-type/SKILL.md','utf8'); if(!s.startsWith('---')) throw new Error('missing frontmatter'); const fm=s.match(/^---\r?\n([\s\S]*?)\r?\n---/); if(!fm) throw new Error('invalid frontmatter'); const keys=[...fm[1].matchAll(/^([A-Za-z0-9_-]+):/gm)].map(m=>m[1]); if(keys.join(',')!=='name,description') throw new Error('unexpected frontmatter keys: '+keys.join(',')); if(!/name: ai-documents-validation-document-type/.test(fm[1])) throw new Error('bad name'); JSON.parse(fs.readFileSync('skills/ai-documents-validation-document-type/evals/evals.json','utf8')); console.log('skill smoke ok');" ``` Se disponibile un Python corretto con `PyYAML`, si puo' eseguire anche: ```bash scripts/quick_validate.py skills/ai-documents-validation-document-type ``` Nel contesto corrente `quick_validate.py` non e' obbligatorio se l'interprete Python disponibile manca di `PyYAML`; lo smoke Node copre frontmatter e JSON eval. Poi fare un dry-run manuale su prompt realistico: ```text Aggiungi supporto a un nuovo certificato in E:\ai-documents-validation. ``` Verificare che l'agente: - legga `AGENTS.md`; - applichi Docs MCP-first o fallback motivato; - non proponga solo classificazione; - includa parser, diagnostica, regole, reliability, API, CLI, test e docs. ## 13. Criteri di done La skill e' pronta quando: - frontmatter contiene solo `name` e `description`; - trigger e anti-trigger sono chiari; - `SKILL.md` e' snello e usa progressive disclosure; - references coprono checklist nuovo tipo, docs-first, diagnostica e test; - eval coprono casi positivi e negativi; - validazione skill passa; - non duplica inutilmente documentazione lunga del repo target; - confini con `mcp-technical-analyst`, `mcp-master-orchestrator`, `mcp-code-reviewer` e `mcp-docs-navigator` sono espliciti. - scenario integrazione API copre endpoint, auth, CORS, request/response, errori, privacy e test consumer. ## 14. Raccomandazione finale Procedere con skill repo-specifica `ai-documents-validation-document-type`. Non creare per ora una skill generica "AI nei programmi". Estrarre una skill generica solo dopo aver osservato almeno un secondo repository con pattern stabile simile: classificazione AI, estrazione strutturata, diagnostica, regole, reliability, superfici pubbliche e test integrati.