Onboarding catalogo PDF in CPQ multi-brand: playbook 7 fasi

Tre studi (stack v2.3, flussi v1.3, wiki narrativo) descrivono cosa costruire e perche'. Questo descrive come iniziare domani: il playbook concreto per onboardare un nuovo catalogo brand (PDF voluminoso) come Knowledge Tool dentro lo stack CPQ multi-brand v2.3.

Sette fasi sequenziali, ognuna con: cosa fare, strumenti, deliverable, prompt template per Claude Code, errori comuni.

Pre-requisiti (cosa deve esistere PRIMA di iniziare)

Checklist da verificare prima della Fase 1. Se manca qualcosa, fermati e completalo.

#	Pre-requisito	Verifica
1	Repo git con accesso scrittura	git status funziona nel progetto
2	VPS/server con Docker Compose attivo	docker compose ps mostra Postgres + Inngest + Langfuse + MCP server esistenti
3	Postgres con estensione pgvector + JSONB	\dx in psql mostra pgvector
4	PIM lite installato con almeno uno schema categoria definito	tabella prodotti esiste, almeno un wiki_<sistema>/categorie/C001_*.md
5	Supervisor minimale (Python if/elif su intent o LangGraph)	endpoint /supervisor/query risponde
6	Almeno un Knowledge Tool brand esistente come template	es. <primo-brand>-knowledge-mcp deployato
7	Anthropic API key valida	ANTHROPIC_API_KEY in .env.local, test con curl
8	Account/credenziali al portale del fornitore	accesso al portale brand per scaricare PDF + schede tecniche
9	Spazio disco: ~5-10 GB liberi sul server	df -h
10	Claude Code installato sul PC dev	claude --version

Fase 1: scelta del brand pilota

Se hai N brand candidati per essere "il prossimo", non sceglierne uno a caso. Quattro criteri pesati.

Criterio	Peso	Domanda
Profondita' catalogo	20%	Il brand ha 100, 500 o 5000 codici? Sotto 200 il valore aggiunto e' marginale.
Qualita' PDF fornitore	30%	Il PDF e' nativo (testo selezionabile)? Ha tabelle ben strutturate? Le formule sono testuali o grafiche?
Frequenza aggiornamenti	15%	Annuale (raro) vs trimestrale (oneroso)? Aggiornamenti rari = ROI maggiore.
Fatturato del brand sul tuo business	35%	Brand top 3 vs longtail? Top brand giustificano l'investimento.

Approccio operativo: assegna 1-5 a ciascun criterio per ogni candidato, calcola pesato, scegli il top.

Prompt template per Claude Code (Fase 1)

Sto valutando di aggiungere il brand "{NOME_BRAND}" come Knowledge Tool al
nostro stack CPQ multi-brand v2.1. Riferimento canonico:
https://andreapellizzari.it/studio/stack-agentico-pmi/

Aiutami a fare scoring secondo i 4 criteri del playbook
(/studio/playbook-onboarding-catalogo-pdf/#fase-1-scelta-del-brand-pilota):
1. Profondita' catalogo (numero codici stimato, ottieni da pagina prodotti)
2. Qualita' PDF fornitore (allegato/link al PDF master se l'ho)
3. Frequenza aggiornamenti (cerca informazioni sull'ultimo update)
4. Fatturato sul nostro business (te lo dico io)

Output: tabella scoring con somma pesata + raccomandazione (pilota / rinviare /
scartare).

Deliverable Fase 1

• Documento decisioni_arch/<data>-scelta-brand-<nome>.md con scoring + decisione finale + razionale + rischi noti.

---

Fase 2: estrazione PDF (MinerU + pdfplumber)

Dual extractor obbligatorio (vedi pattern in dettaglio). Nessun OCR singolo copre il 100%.

Strumenti

• MinerU (CLI Python) per markdown strutturato + tabelle
• pdfplumber (libreria Python) per raw text supplementare
• PyMuPDF (fitz) per pre-render JPG di tutte le pagine (citazioni inline)

Steps

1. Crea cartella destinazione: families/<brand_id>/ (es. families/<brand>/).
2. Copia il PDF master: families/<brand>/source.pdf.
3. Lancia MinerU: produce extracted.md + immagini segmentate.
4. Lancia pdfplumber con script ad-hoc: produce extracted_supplementary.md raw text.
5. Pre-render pagine in JPG a 150 DPI: manuale_pages/pag-NNN.jpg (per chip citazione inline). ~5 min per 800 pagine, ~130 MB totali.
6. Costruisci breadcrumb pagine: parser su extracted.md per estrarre titoli H1-H4 -> CSV pagine_breadcrumb.csv.
7. Costruisci albero del manuale: albero_manuale.md con struttura gerarchica (utile per diff fra edizioni).
8. _status.json per famiglia: marker che la pipeline ha completato (verde/rosso).

Tempi attesi

Pagine PDF	MinerU	pdfplumber	PyMuPDF render	Totale
200	15-30 min	1-2 min	1-2 min	20-35 min
500	40-60 min	3-5 min	3-5 min	50-70 min
1000	1.5-2.5 h	6-10 min	6-10 min	2-3 h

Errori comuni

• PDF scansionato non nativo: MinerU restituisce poco. Soluzione: passare per OCR pre-process (ocrmypdf) prima.
• Tabelle complesse multi-pagina: MinerU le spezza male. Soluzione: vision Claude in-session sulle pagine specifiche dopo l'estrazione (vedi sezione 8 di wiki narrativo).
• Formule grafiche perse: cattura via pdfplumber (raw text recupera glifi che MinerU smaltisce).

Prompt template per Claude Code (Fase 2)

Sto estraendo il PDF del brand "{NOME_BRAND}" (file in
families/{brand_id}/source.pdf, {NUM_PAGINE} pagine).

Riferimento metodologico:
/studio/wiki-narrativo-ai-maintained/#1-pipeline-ocr-ingest-dal-pdf-ai-chunk-searchable

Spawna un agente Explore che:
1. Verifica che source.pdf esiste e e' apribile
2. Lancia MinerU CLI con output in families/{brand_id}/mineru_out/
3. Lancia uno script pdfplumber che produce extracted_supplementary.md
4. Lancia pdftoppm o PyMuPDF per pre-render JPG 150 DPI in
   blum_data/manuale_pages/pag-NNN.jpg (sostituisci 'blum_data' col path
   del tuo media folder)
5. Costruisce pagine_breadcrumb.csv parsando i titoli di extracted.md
6. Scrive families/{brand_id}/_status.json con esito + statistiche

Riporta dimensioni output, eventuali errori, suggerimenti di pagine critiche
per le quali probabilmente serve vision in-session.

Deliverable Fase 2

• families/<brand>/source.pdf
• families/<brand>/extracted.md (MinerU)
• families/<brand>/extracted_supplementary.md (pdfplumber)
• media/manuale_pages/pag-NNN.jpg (per citazioni inline)
• families/<brand>/pagine_breadcrumb.csv
• families/<brand>/albero_manuale.md
• families/<brand>/_status.json

---

Fase 3: definizione CategorySchema (PIM lite)

Prima di scrivere il wiki narrativo, definisci o aggiorna lo schema attributi per le categorie del brand. Questo decide come il PIM filtrera' i prodotti cross-brand.

Decisioni da prendere

1. Le categorie del brand sono nuove o gia' esistenti nel PIM?
   • Esistenti (es. il PIM ha gia' C001_lavastoviglie.md): aggiungi solo il brand al valori dell'attributo brand di quella categoria.
   • Nuove (es. mai entrato il segmento "ferramenta cerniere"): definisci da zero C00N_<categoria>.md con tutti gli attributi tipizzati.
2. Schema categoria condiviso o brand-specifico?
   • Condiviso (raccomandato): C001_lavastoviglie.md ha gli stessi attributi per Bosch / Whirlpool / BSH. La domanda "lavastoviglie 60 classe A" funziona cross-brand.
   • Brand-specifico (sconsigliato): C001_lavastoviglie_bosch.md separato. Si perde la query cross-brand. Solo se gli attributi sono veramente diversi per natura.

Pattern Karpathy esteso (vedi wiki narrativo)

Lo schema vive in MD-Karpathy editabile da UI. Esempio:

---
id: C001
categoria: lavastoviglie
versione: 1.1                   # bump quando aggiungi nuovo brand o nuovo attributo
ereditato_da: C000_elettrodomestico_incasso
attributi:
  - { nome: larghezza_cm, tipo: measurement, unita: cm, valori_tipici: [45, 60] }
  - { nome: classe_energetica, tipo: select, valori: [A, B, C, D, E, F, G] }
  - { nome: capacita_coperti, tipo: measurement, unita: coperti }
  - { nome: tipo_incasso, tipo: select, valori: [totale, scomparsa_parziale, libero_installazione] }
  - { nome: brand, tipo: select, valori: [bosch, whirlpool, bsh, NEW_BRAND] }   # AGGIUNGI QUI
  - { nome: modello, tipo: text }
  - { nome: codice, tipo: text, identifier: true }
---

# C001 - Lavastoviglie

(narrativa)

Disciplina di versioning

• Bump patch (1.1.1) per fix typo o riformulazione narrativa.
• Bump minor (1.2) per nuovo attributo o nuovo brand aggiunto.
• Bump major (2.0) per ristrutturazione (es. attributi rinominati: serve migration dei dati prodotto esistenti).

Errori comuni

• Aggiungere attributi "ad-hoc per il nuovo brand": significa inventare attributi che il brand precedente non ha mai avuto. Rompe la query cross-brand. Soluzione: o l'attributo e' valido per tutti i brand della categoria (e va nello schema condiviso), o vive nel wiki narrativo del brand specifico (non nel PIM).
• Confondere valori_tipici con valori: valori (per select) e' la lista chiusa ammessa (validata). valori_tipici (per measurement) e' indicativa per UI/suggerimenti, ma il valore reale puo' essere qualsiasi numero nell'unita'.
• Saltare la versione: senza bump, il PIM non sa quale schema applicare alla categoria. La validazione fallisce silenziosamente.

Prompt template per Claude Code (Fase 3)

Devo aggiungere il brand "{NOME_BRAND}" alle categorie esistenti del PIM
del nostro stack CPQ v2.1.

Categorie del brand (da decidere insieme): {ELENCO_CATEGORIE_BRAND}
es: ["lavastoviglie", "frigorifero_incasso", "forno_incasso"]

Riferimenti:
- /studio/stack-agentico-pmi/#3b-pim-lite-per-attributi-cross-brand
- /studio/playbook-onboarding-catalogo-pdf/#fase-3-definizione-categoryschema-pim-lite

Per ogni categoria del brand:
1. Leggi wiki_<sistema>/categorie/C*.md esistenti
2. Se la categoria esiste gia' (es. C001_lavastoviglie.md), proponi un diff
   minimale: aggiungere il brand al valori di 'brand', bump versione
3. Se la categoria e' nuova, proponi un nuovo C00N_<categoria>.md scaffold
   guardando il manuale del brand per estrarre attributi tipizzati comuni
   (larghezza, classe, capacita, ecc.)

Output:
- diff per ogni file MD esistente
- bozza completa per ogni file MD nuovo
- domande aperte (es: "questo attributo del brand X non esiste in Y, ti
  conviene metterlo nel wiki narrativo invece che nello schema?")

Non scrivere ancora i file: voglio review prima.

Deliverable Fase 3

• wiki_<sistema>/categorie/C*.md aggiornati o nuovi.
• Bump versione di ogni categoria modificata.
• Test al PIM (al boot deve ricaricare lo schema senza errori).

---

Fase 4: cura wiki narrativo del brand (D*/G*/R*/F*)

Adesso scrivi il wiki Karpathy del brand. Quattro categorie di file (vedi wiki narrativo cap. 2):

Categoria	File	Cosa contiene	Quando crearne uno
Distinte (D*.md)	wiki_<brand>/distinte/D001_<famiglia>.md	Composizione canonica per famiglia (lista componenti, pattern codici, optional, errori da non fare)	Una per famiglia "configurabile"
Guide (G*.md)	wiki_<brand>/guide/G002_<scelta>.md	Decision tree narrativo per scelte ("scegli X vs Y vs Z")	Una per asse decisionale ricorrente
Regole (R*.md)	wiki_<brand>/regole/R002_<regola>.md	Regola tecnica con frontmatter eseguibile (vedi Fase 5)	Una per regola/formula trasversale
Famiglie (F*.md)	wiki_<brand>/famiglie/F001_<famiglia>.md	Scheda narrativa "cos'e' X, quando sceglierla, quando NO"	Una per famiglia user-facing

Ordine consigliato di scrittura

1. F (famiglie) prima*: sono il piu' veloce da scrivere e danno una "anagrafica narrativa" di base. 1 famiglia = 1 ora circa.
2. G (guide) seconde*: danno il decision tree che il bot useremo per i casi "come scelgo".
3. D (distinte) terze*: piu' complesse, richiedono di mettere insieme codici reali. 1 distinta = 2-3 ore.
4. R (regole) per ultime*: vedi Fase 5 dedicata, con frontmatter eseguibile.

Strumenti operativi

• Editor wiki UI (esempio gia' presente nel template di riferimento): browser su http://<host>/editor con whitelist email. Scrittura assistita + AI auto-fix sui feedback.
• Validator AI pre-save (vedi v2.0 sezione 3A): blocca syntax MD rotta, codici Blum inventati (cit), sigle interne user-facing.
• Lint workflow mensile: orphan pages, stale claims, concept menzionati senza scheda. Task DoIt schedulato.

Prompt template per Claude Code (Fase 4)

Devo scrivere il wiki narrativo per il brand "{NOME_BRAND}", categoria
"{CATEGORIA}" (es. lavastoviglie).

Riferimenti:
- /studio/wiki-narrativo-ai-maintained/#2-wiki-autoritativo-a-4-categorie
- /studio/playbook-onboarding-catalogo-pdf/#fase-4-cura-wiki-narrativo-del-brand
- pattern di esempio: wiki_<brand_template>/famiglie/F001_<famiglia>.md
  (usa il primo Knowledge Tool brand esistente come modello)

Spawna un sub-agente Explore (max 1, NO parallelo per evitare rate limit) che:
1. Legge families/<brand>/extracted.md per la sezione della categoria scelta
2. Identifica le famiglie principali (es. lavastoviglie scomparsa totale,
   parziale, libero installazione)
3. Per la famiglia che ti indico, scrive bozza F001_<famiglia>.md seguendo
   il template di riferimento:
   - frontmatter YAML (id, brand, categoria, pag_start, pag_end)
   - sezione "Cos'e'": narrativa user-facing
   - sezione "Quando sceglierla / Quando NO": consulenza
   - sezione "Codici tipici": SOLO codici verificati nell'estratto
   - sezione "Vedi anche": cross-link [[D001 ...]] [[G001 ...]] [[R001 ...]]

CRITICO: NON inventare codici articolo. Se non vedi il codice
nell'extracted.md, NON metterlo. Se hai dubbi, scrivi `# TODO verificare
manualmente` e segnalalo.

Output: bozza MD completa, lista codici usati con riferimento a pagina manuale,
lista TODO da verificare manualmente.

Errori comuni

• Inventare codici: il LLM tende a "completare" codici plausibili. Soluzione: validator AI pre-save che cerca pattern di codici e li verifica contro extracted.md / DB.
• Cross-link rotti ([[D001 ...]] che non esiste): lint workflow li trova. Fix: rinominare correttamente o rimuovere il link.
• Sigle interne user-facing: l'esperto del brand usa sigle (KH, FH, NL, LF nel caso ferramenta) che il bot rivolto al cliente non deve usare senza spiegare. Validator AI le segnala.
• Spawn troppi sub-agenti in parallelo: rate limit Anthropic. Massimo 2 sub-agenti contemporaneamente, meglio 1.

Deliverable Fase 4

• wiki_<brand>/famiglie/F*.md (una per famiglia user-facing, ~5-15 file)
• wiki_<brand>/guide/G*.md (5-10 file decision tree)
• wiki_<brand>/distinte/D*.md (per famiglie configurabili, 5-15 file)
• 0 broken link interni (verifica con script audit_wiki.py)
• 0 codici inventati (verifica con audit_wiki.py cross-ref con extracted.md)

---

Fase 5: definizione Rule (R*.md frontmatter eseguibile)

Le regole tecniche del brand, scritte come MD-Karpathy con frontmatter eseguibile per Rule Engine deterministico (vedi wiki narrativo: frontmatter eseguibile).

Cosa cattura una regola

Vincoli tecnici espliciti, non interpretazioni discorsive. Esempi:

• "Se anta > 18 kg, usa cerniera high-load" -> regola con condizione su peso_anta_kg.
• "Per lavastoviglie 60 cm e cassetto retrostante < 560 mm, segnala rischio nicchia" -> regola cross-modulo.
• "Per cucina 60 con sistema cassetti X, profondita' minima nicchia elettrodomestico Y mm" -> regola cross-categoria.

Schema del frontmatter

id: R005
nome: "Cassetto: set guida X vs Y per portate alte"
ambito: <brand>.<famiglia>            # es. blum.legrabox, bosch.lavastoviglie, cross.compat
versione: 1.0
fonte_pagine_fis: [248]               # pagine manuale per citazione

condizione:
  all_of:
    - { fatto: famiglia, op: "=", valore: legrabox }
    - { fatto: portata_kg, op: ">", valore: 40 }
    - { fatto: NL_mm, op: ">", valore: 500 }
azione: warn                          # allow | warn | suggest | block
messaggio_template: "Per portata {{portata_kg}}kg e NL {{NL_mm}}mm usa Y, non X."

test_cases:
  - { in: {famiglia: legrabox, portata_kg: 70, NL_mm: 600}, expect: warn }
  - { in: {famiglia: legrabox, portata_kg: 40, NL_mm: 400}, expect: pass }

Da dove arrivano le regole

Tre fonti pratiche, in ordine di valore:

1. Manuale del fornitore (sezioni "informazioni applicative", "regole di montaggio", "vincoli tecnici"). E' il giacimento principale.
2. Esperti interni che lavorano col brand da anni (commerciali tecnici, tecnici showroom). Conoscono i casi limite e gli errori frequenti.
3. Feedback degli utenti del bot (segnalazioni di errori): quando un utente segnala "il bot mi ha consigliato X ma non funziona", spesso emerge una regola che mancava.

Strumento: editor regole

L'editor wiki UI espone i R*.md come gli altri file. L'esperto puo' modificare body narrativo + tabella decisione + (con minimo training) il blocco condizione del frontmatter.

Il validator AI pre-save verifica:

• Syntax YAML del frontmatter.
• condizione ben formata (combinatori validi, fatti referenziati).
• test_cases passano (ogni test in -> azione attesa).

Prompt template per Claude Code (Fase 5)

Devo estrarre le regole tecniche per il brand "{NOME_BRAND}", categoria
"{CATEGORIA}" dal manuale (families/<brand>/extracted.md).

Riferimenti:
- /studio/wiki-narrativo-ai-maintained/#frontmatter-eseguibile-estensione-v2-0-per-rule-engine
- /studio/stack-agentico-pmi/#3c-rule-engine-deterministico
- /studio/playbook-onboarding-catalogo-pdf/#fase-5-definizione-rule

Spawna un sub-agente che:
1. Legge la sezione "informazioni applicative" / "regole tecniche" /
   "tabelle vincoli" del manuale (~10-30 pagine tipiche)
2. Identifica regole esplicite: vincoli numerici, soglie, decision tree
3. Per ogni regola identificata, propone un R*.md con:
   - frontmatter standard (id, nome, ambito, versione, fonte_pagine_fis)
   - condizione formalizzata in DSL JSON (all_of/any_of, fatto/op/valore)
   - azione (allow/warn/suggest/block)
   - messaggio_template (con {{var}} per substitution)
   - test_cases (almeno 2: uno che triggera, uno che non triggera)
4. Per ogni regola, body narrativo con: contesto, tabella decisione, note,
   vedi-anche (cross-link)

CRITICO: se la regola non e' esplicita nel manuale ma "dedotta", segnala
'inferenza-non-verificata' e NON la aggiungere automaticamente. Le regole
inventate dal LLM sono pericolose.

Output: lista R*.md proposti, lista regole "inferite" da verificare con
esperto, eventuali pagine vision-needed (se la regola sta in un disegno
quotato che MinerU non ha catturato bene).

Errori comuni

• Regole inferite ma non documentate: il LLM "estrapola" da poche evidenze. Soluzione: marker esplicito "inferenza non verificata", validare con esperto prima di committare.
• Test cases che non riflettono la regola: il test deve essere il caso piu' rappresentativo della condizione, non un edge case strano.
• Ambito troppo largo o troppo stretto: ambito: bosch (troppo largo) vs ambito: bosch.lavastoviglie.modello_X (troppo stretto). Tipicamente: <brand>.<famiglia> o cross.compat per cross-modulo.

Deliverable Fase 5

• wiki_<brand>/regole/R*.md (5-15 file tipici per brand maturo)
• Tutti i test_cases passano (pre-commit hook)
• 0 regole "inferite-non-verificate" mergiate nel main

---

Fase 6: build Knowledge Tool MCP

Adesso impacchetti il wiki + dataset come MCP server. Il template e' il primo Knowledge Tool brand esistente.

Componenti del Knowledge Tool

<brand>-knowledge-mcp/
├── data/
│   ├── chunks.db                    # SQLite con chunks + embeddings
│   ├── codici.db                    # SQLite con anagrafica codici (da extracted.md)
│   └── manuale_pages/               # JPG citazioni inline
├── wiki_<brand>/                    # MD-Karpathy editabile (D*/G*/R*/F*)
├── server.py                        # FastMCP entry point
├── tools/
│   ├── cerca_knowledge.py           # hybrid retrieval BM25 FTS5 + cosine + RRF
│   ├── dettaglio_codice.py          # lookup esatto
│   ├── valida_compatibilita.py      # validazione consulenziale (chiama Rule Engine)
│   └── ... (tool dominio-specifici)
├── pipeline/
│   ├── chunk_wiki.py                # chunking dei MD
│   ├── embed_chunks.py              # sentence-transformers 768d
│   └── reindex.py                   # rebuild DB
├── Dockerfile
└── requirements.txt

Tre tool minimi di contratto comune (obbligatori)

Ogni Knowledge Tool brand deve esporre questi tre tool per essere consumabile dal Supervisor:

@mcp.tool()
def cerca_knowledge(query: str, top_k: int = 5, alpha: float = 0.5) -> list[dict]:
    """Hybrid retrieval BM25 + cosine + RRF nel wiki di questo brand."""
    # vedi /studio/stack-agentico-pmi/#3a-knowledge-tools-per-brand-constellation-di-mcp

@mcp.tool()
def dettaglio_codice(codice: str) -> dict:
    """Lookup esatto di un codice nel catalogo di questo brand."""

@mcp.tool()
def valida_compatibilita(prodotto: dict, contesto: dict) -> dict:
    """Validazione consulenziale. Applica regole tecniche del brand
    (chiama Rule Engine). Ritorna {ok, status, motivazione, alternative}."""

Plus tool dominio-specifici (assemble_distinta, get_regola, get_media, ecc.) come per il primo Knowledge Tool.

Strumenti

• FastMCP Python
• SQLite con FTS5 nativo (per BM25 hybrid)
• sentence-transformers (mpnet 768d) per embedding
• Docker Compose per deploy

Prompt template per Claude Code (Fase 6)

Devo costruire il Knowledge Tool MCP per il brand "{NOME_BRAND}".
Template di riferimento: il primo Knowledge Tool brand esistente
(es. <primo-brand>-knowledge-mcp).

Riferimenti:
- /studio/stack-agentico-pmi/#3a-knowledge-tools-per-brand-constellation-di-mcp
- /studio/playbook-onboarding-catalogo-pdf/#fase-6-build-knowledge-tool-mcp

Spawna un sub-agente che:
1. Clona la struttura del template <primo-brand>-knowledge-mcp in
   <brand>-knowledge-mcp
2. Sostituisce wiki_<primo-brand>/ con wiki_<brand>/ (i file scritti in Fase 4-5)
3. Lancia pipeline/chunk_wiki.py per chunkare D*/G*/R*/F*
4. Lancia pipeline/embed_chunks.py per generare embeddings 768d
5. Verifica che i 3 tool minimi di contratto comune siano implementati e
   funzionanti (smoke test su query di esempio)
6. Aggiunge tool dominio-specifici se utili (es. assemble_distinta per
   famiglie configurabili)
7. Build Docker, deploy in docker-compose.yml accanto agli altri MCP server
8. Smoke test: chiama cerca_knowledge("query test"), verifica risposta

Output: report di build + log dei test + URL endpoint MCP per registrazione
nel Supervisor.

Smoke test obbligatori prima di andare alla Fase 7

• cerca_knowledge("una query rappresentativa") ritorna almeno 1 chunk con score > 0.5.
• dettaglio_codice("<codice_reale_dal_manuale>") ritorna l'anagrafica completa.
• valida_compatibilita({...}, {...}) ritorna struttura {ok, status, motivazione} per un caso di test.

Deliverable Fase 6

• Repo <brand>-knowledge-mcp/ deployato e in esecuzione.
• 3 smoke test passati.
• Documentato in decisioni_arch/<data>-deploy-<brand>-knowledge.md.

---

Fase 7: integrazione con Supervisor (Filter-then-Validate)

Adesso registri il nuovo Knowledge Tool nel Supervisor e attivi i flussi cross-brand che includono il brand.

Step

1. Aggiungi mapping brand -> knowledge_tool nel Supervisor:

   knowledge_tools = {
       "blum": BlumKnowledgeMCP("http://blum-knowledge:8000"),
       "bosch": BoschKnowledgeMCP("http://bosch-knowledge:8000"),
       "<NEW_BRAND>": NewBrandKnowledgeMCP("http://<new-brand>-knowledge:8000"),  # AGGIUNGI
   }
   

2. Verifica che il PIM ha il brand nei valori della categoria (Fase 3).
3. Smoke test Filter-then-Validate cross-brand: lancia una query come quelle del Flusso 5. Verifica che:
   • PIM include il nuovo brand nei candidati;
   • Knowledge Tool del nuovo brand viene chiamato con valida_compatibilita;
   • Sintesi mostra il nuovo brand nelle 3 colonne (compatibile / consigliato / sconsigliato).
4. Aggiorna eval set: aggiungi 5-10 casi di test che includono il nuovo brand. Lancia regression: tutti devono passare.
5. Deploy in produzione: rolling con osservabilita' attiva (Langfuse trace di ogni query nei primi giorni).
6. Monitor 1 settimana: occhio ai trace Langfuse per casi anomali. Tipico: regole troppo strette o troppo lasche, codici inventati nel wiki, vincoli cross-modulo non triggerati.

Prompt template per Claude Code (Fase 7)

Devo integrare il nuovo brand "{NOME_BRAND}" nel Supervisor v2.1.

Riferimenti:
- /studio/stack-agentico-pmi/#livello-2-supervisor-pattern-filter-then-validate
- /studio/flussi-agentici-pmi/#flusso-5-query-strutturata-cross-brand-filter-then-validate
- /studio/playbook-onboarding-catalogo-pdf/#fase-7-integrazione-con-supervisor-filter-then-validate

Spawna un sub-agente che:
1. Aggiorna il mapping knowledge_tools nel Supervisor aggiungendo il nuovo brand
2. Verifica nel PIM che il valore "{nome_brand_kebab}" sia nei `valori` della
   categoria (vedi Fase 3)
3. Aggiunge 5-10 casi di test all'eval set, includendo:
   - 1 lookup esatto codice del nuovo brand
   - 2 query consult single-brand (consulenza tecnica)
   - 2 query search cross-brand (Filter-then-Validate)
   - 1 query con vincolo cross-modulo che triggera Rule Engine
   - 1 edge case noto del brand
4. Lancia regression eval: tutti i casi (vecchi + nuovi) devono passare
5. Smoke test live di una query Flusso 5 cross-brand

Output: log eval, log smoke test, eventuali fail con root cause analysis,
checklist deploy production.

Errori comuni

• Knowledge Tool non risponde: rete Docker, MCP transport, env vars. Verifica con curl diretto al tool.
• Eval regression: nuovi test passano ma quelli vecchi fail -> il nuovo Knowledge Tool ha "rubato" candidati ad altri brand (es. PIM ranking sballato). Soluzione: rivedere il PIM ranking o tarare alpha del hybrid retrieval.
• Vincoli cross-modulo non triggerati: il Rule Engine non vede il nuovo brand nelle regole cross.compat. Soluzione: aggiornare le regole cross.compat per includere il nuovo brand dove rilevante.

Deliverable Fase 7

• Supervisor riconosce il nuovo brand.
• Eval set esteso (target: 5-10 casi nuovi, tutti passano).
• Smoke test live con Flusso 5 cross-brand riuscito.
• Deploy production con osservabilita' attiva.

---

Stima tempi realistica

Brand #	Tempo totale	Note
1° (setup base)	~10-13 settimane	Vedi Migration path BlumCat -> v2.1. Include impostazione Supervisor, PIM, Rule Engine.
2° brand	2-3 settimane	Primo onboarding "vero" col playbook. La maggior parte del tempo va in Fase 4 (wiki narrativo) e Fase 5 (regole).
3° brand	1-2 settimane	Hai gia' il template, sai dove sono le insidie.
4°-5° brand	5-7 giorni	Pipeline rodata. Bottleneck: cura wiki narrativo (non automatizzabile, richiede esperto).
6°+ brand	3-5 giorni	Bottleneck: solo cura wiki. Tutto il resto e' "premere play".
30° brand (orizzonte 2-3 anni)	2-3 giorni	A regime: pipeline industriale.

Anti-pattern e errori comuni

Sintesi dei rischi visti finora, da tenere come checklist mentale prima di ogni fase.

Errori di processo

• Saltare i pre-requisiti ("tanto sistemo dopo"): porta a setup half-baked che si bloccano a meta'. La checklist e' un gate, non una formalita'.
• Brand pilota scelto a caso: porta a costi/risultato squilibrati. Il primo brand "vero" e' quello che insegna; sceglierlo male significa imparare le lezioni sbagliate.
• Cura wiki delegata all'AI senza supervisione esperto: il LLM scrive narrativa plausibile ma con codici inventati e regole inferite. Il validator AI cattura il 70%, ma il restante 30% richiede esperto umano.

Errori tecnici

• Schema PIM "ad-hoc per il nuovo brand": rompe la query cross-brand. Schema condiviso per categoria, brand come attributo.
• Inventare codici: il LLM tende a "completare". Validator AI + audit script cross-ref con extracted.md.
• Cross-link rotti: lint workflow mensile. Pre-commit hook se possibile.
• Spawn sub-agenti in parallelo > 2: rate limit Anthropic. Massimo 2, meglio 1.
• Saltare smoke test: deploy senza smoke test = deploy con bug nascosti che emergono in produzione. Mai.

Errori conversazionali (col bot in produzione)

• Knowledge Tool che inventa codici: 1 segnalazione utente -> apri il wiki, cerca il codice, se non c'e' aggiungi nota "codice X non disponibile nel catalogo Y" come F*.
• Filter-then-Validate che non triggera vincoli cross-modulo: il Rule Engine non vede il nuovo brand. Aggiornare regole cross.compat.
• Three-state UI confusa (compatibile / consigliato / sconsigliato): se l'utente non capisce la distinzione, rivedere il template di sintesi del Supervisor.

Prompt template generale per Claude Code

Quando inizi una sessione Claude Code per qualsiasi onboarding nuovo brand, comincia sempre con questo prompt (assicura coerenza con stack v2.1):

Sto onboardando il brand "{NOME_BRAND}" come Knowledge Tool nel nostro stack
CPQ multi-brand v2.1.

Contesto canonico (riferimenti autoritativi):
- Stack v2.1: https://andreapellizzari.it/studio/stack-agentico-pmi/
- Flussi v1.3: https://andreapellizzari.it/studio/flussi-agentici-pmi/
- Wiki narrativo Karpathy: https://andreapellizzari.it/studio/wiki-narrativo-ai-maintained/
- Playbook 7 fasi: https://andreapellizzari.it/studio/playbook-onboarding-catalogo-pdf/

Vincoli:
- Modello bi-dimensionale (knowledge verticale per brand + cross-cutting
  orizzontale per dato strutturato)
- Pattern Filter-then-Validate per query cross-brand (PIM filtra, Knowledge
  valida, tre stati: compatibile/consigliato/sconsigliato)
- Karpathy come fondazione di rappresentazione del knowledge editabile
  (NON come architettura completa)
- Hybrid retrieval BM25 FTS5 + cosine + RRF (k=60) come default in
  cerca_knowledge
- Niente codici inventati: sempre verificati contro extracted.md o DB
- Sub-agenti spawn max 2 in parallelo per evitare rate limit Anthropic

Sono alla Fase {N} del playbook. Aiutami con: {DESCRIZIONE_TASK}.

Prima di scrivere codice o file, conferma che hai letto i 4 riferimenti sopra
e dimmi che approccio segui.

Questo prompt forza il LLM a:

• Caricare il contesto dei 4 documenti canonici (via web fetch).
• Esplicitare quali vincoli sta rispettando.
• Allinearsi alla terminologia v2.1 (Knowledge Tool, Filter-then-Validate, Karpathy, hybrid retrieval).
• Chiedere conferma di approccio prima di partire (riduce drift architetturale).

Per il modello architetturale completo entro cui questo playbook vive, vedi Agentizzare una PMI: stack v2.1. Per il pattern del livello knowledge editabile (wiki Karpathy), vedi Wiki narrativo AI-maintained. Per esempi end-to-end di flussi che includono il nuovo brand una volta integrato, vedi Agentizzare un'azienda: timeline e flussi reali.

Registro aggiornamenti

1. 2026-05-05v1.2

   Esplicitato il meta-pattern "Claude-assisted ingest" in cima al playbook. Tutte le fasi (estrazione PDF, definizione CategorySchema, cura wiki narrativo, definizione Rule, build Knowledge Tool MCP) sono Claude-assisted: developer + Claude Code in sessione iterativa scrivono gli script Python che fanno il lavoro pesante. L'esperto interno non edita YAML/JSON, corregge body narrativo + aggiunge nozioni mentali. Cross-link al master v2.3 dove il razionale strutturale e' formalizzato (riduzione effort 5-10x rispetto a pattern data engineering tradizionale). Tempi di onboarding nelle tabelle restano validi: questa e' chiarificazione di metodo, non revisione tempi.

2. 2026-05-05v1.1

   Allineamento versioni dei riferimenti documentali: bumpati i riferimenti "stack v2.0" → "stack v2.1" e "flussi v1.2" → "flussi v1.3" per riflettere le versioni correnti dei documenti citati nei prompt template per Claude Code. I prompt ora puntano alle versioni piu' aggiornate degli studi correlati. Il design architetturale resta v2.0 (la versione 2.1 e' un allineamento tooling, non un nuovo rework).

3. 2026-05-05v1.0

   Prima stesura. Playbook operativo a 7 fasi per onboarding di un nuovo catalogo brand (PDF voluminoso) come Knowledge Tool dentro lo stack CPQ multi-brand v2.1. Per ogni fase: cosa fare, strumenti, deliverable, prompt template per Claude Code, errori comuni. Stima tempi realistica per il primo, secondo, decimo brand. Anti-pattern di processo e tecnici. Prompt template generale per Claude Code che forza coerenza con i 4 documenti canonici dello stack v2.1 (stack, flussi, wiki narrativo, questo playbook).