Streamwave BI

Progetto di Business Intelligence sviluppato con approccio spec-driven (GitHub Spec Kit).

StreamWave, piattaforma di streaming video, valuta l'ingresso nel verticale del music streaming. Questo repository contiene l'analisi e la dashboard a supporto della decisione.

Tre domande di business guidano l'intero progetto:

• BQ1 — Posizionamento: come si posiziona il contenuto musicale rispetto a quello video per caratteristiche "vincenti" (durata, genere, mood)? C'è overlap di audience potenziale?
• BQ2 — Segmento di ingresso: quale segmento musicale è più coerente con il catalogo attuale?
• BQ3 — Impatto stimato: quale impatto su engagement e revenue, simulato con assunzioni dichiarate?

I principi non negoziabili del progetto — etichettatura di fonte e confidenza su ogni numero, riproducibilità totale, trasparenza sui limiti — sono in .specify/memory/constitution.md. Il metodo di lavoro che ne discende, incluso il modo in cui il lavoro è diviso fra sessioni di agent, è in CLAUDE.md.

Cosa questo progetto non è

È un case study: un esercizio di analisi costruito per essere verificabile, non un prodotto pronto a supportare una decisione di mercato reale. Nello specifico:

• StreamWave non esiste. È un'azienda inventata. Nessun dato reale di StreamWave è stato usato, perché non ce n'è.
• Netflix e Spotify sono proxy, non StreamWave. Il catalogo Netflix rappresenta il catalogo ipotetico di StreamWave, il dataset Spotify rappresenta il mercato musicale accessibile. È l'assunzione strutturale del case study: regge il ragionamento, non la realtà di un'azienda.
• Le metriche di business sono sintetiche. Nessun dato di visione, ascolto, abbonamento o ricavo reale esiste in questi dataset. Tutto ciò che riguarda engagement e revenue è generato da script con assunzioni dichiarate, ed è etichettato come tale in ogni artefatto.
• Manca il lato costi. Licenze musicali, infrastruttura, organico: nessuno di questi dati è disponibile. Quello che segue è un business case di opportunità, non un business case finanziario. Chi cercasse qui un ROI non lo troverà, ed è deliberato.
• I dati reali si fermano al 2021-2022. Il catalogo Netflix è aggiornato al 2021, le tracce Spotify al 2022. Nessuna conclusione di questo progetto può dire alcunché sulle dinamiche di mercato successive.

I limiti analitici specifici di ogni singola analisi — cosa quel particolare KPI non risponde, quali inferenze evitare — vivono nella sezione Limiti Dichiarati della spec di ciascuna feature sotto specs/, come richiesto dal principio IV della constitution. Questa sezione inquadra il progetto; quelle inquadrano i singoli risultati.

Stato

Governance: constitution v1.2.0 · metodo di lavoro

Feature	Deliverable	Stato
001 Business Case & KPI Framework	docs/business_case.md	✅ conclusa, revisionata
002 Data Audit & Profiling	docs/data_audit.md · reports/data_profile.json	✅ conclusa, revisionata
003 Data Cleaning & ETL	docs/data_cleaning.md · scripts/build_datasets.py · reports/cleaning_report.json	✅ conclusa, revisionata
004 Synthetic Business Metrics	docs/bq3_scenarios.md · data/benchmarks/ · reports/bq3_scenarios.json	✅ conclusa, revisionata
005 Data Model Design	docs/data_model.md	✅ conclusa, revisionata
006 Content Taxonomy Bridge	docs/content_taxonomy_bridge.md · docs/mood_assignment_criteria.md · data/curated/	✅ conclusa, revisionata
007a Operatori delle misure	docs/kpi_operators.md	✅ conclusa, revisionata
007b Misure dei KPI	docs/kpi_measures.md · scripts/build_kpi_measures.py · reports/kpi_measures.json · reports/kpi_engine_check.json	✅ conclusa, revisionata
008a Dashboard — modello e pagine	il .pbix non versionato, reso ispezionabile dal contratto di pagina e dall'esito della costruzione	✅ conclusa, revisionata
008b Dashboard — narrazione e limiti a schermo	il contratto di narrazione e l'esito della costruzione — il testo dei 32 blocchi portati a schermo	⚠️ chiusa senza raggiungere il proprio obiettivo, revisionata
009 Il verdetto e la raccomandazione	docs/raccomandazione.md	✅ conclusa, revisionata
010a Il report a dieci pagine — disegno	il contratto di pagina, che disegna il report che sostituisce la dashboard a quattro pagine	✅ conclusa, revisionata
010b Il report a dieci pagine — costruzione	il .pbix non versionato, preparato dal contratto delle misure e dal contratto di narrazione	✅ conclusa, implementazione modificata (nota dell'autore)

Ogni feature conclusa ha la propria cartella sotto specs/, con la spec, il piano e — dove esiste — il verbale di revisione.

Il business case

Il primo deliverable è docs/business_case.md: il framework con cui il progetto risponderà alle tre domande. Definisce 8 KPI con formula concettuale, fonte e livello di confidenza, una North Star metric e il perimetro di ciò che l'analisi non proverà a dimostrare. Non contiene risultati: quelli arriveranno dalle feature successive, ciascuno con l'etichetta di affidabilità definita qui.

Il secondo è docs/data_audit.md: il profilo dei due dataset reali, con ciò che la loro forma vincola per le feature successive. Ogni numero che contiene è rigenerato da uno script e vive in reports/data_profile.json, versionato perché sia verificabile anche da chi non ha i dati di origine.

Il terzo è docs/data_cleaning.md: la dichiarazione di ogni decisione presa sui dati per portarli allo stato in cui il modello li userà, con la ragione, l'effetto misurato in righe o valori, e i valori del profilo che dopo la trasformazione non valgono più. I dataset che ne escono non sono versionati (lo è la pipeline che li produce) quindi il documento e reports/cleaning_report.json sono ciò che li rende verificabili da chi non può rigenerarli.

Il quarto è docs/bq3_scenarios.md: i parametri di scenario della terza domanda di business, gli unici numeri del progetto che non descrivono un dato osservato. Il tasso su cui poggiano è un benchmark pubblicato da un terzo, congelato in data/benchmarks/ con la propria citazione e con lo scarto fra ciò che la fonte misura e ciò per cui viene usato; da lì una derivazione deterministica ricava i sei valori di reports/bq3_scenarios.json. Il documento esiste per dichiarare quel passaggio affinché sia trasparente: ancorare un parametro a una fonte lo rende verificabile, non vero per StreamWave.

Il quinto è docs/data_model.md: il modello dati su cui le misure verranno calcolate: quali tabelle esistono, che cosa è una riga di ciascuna, come sono collegate e da quale campo proviene ogni colonna. Esiste come documento e non come file di Power BI perché la constitution lo impone: schema e mapping dei campi sono artefatti testuali, non contenuto di un file binario. Chiarisce cosa sia un «segmento» e quante nozioni di grana servano per descrivere un KPI, e dichiara ciò che il modello rende impossibile misurare, incluse le due tabelle che non esistono di proposito. Il modello è progettato e non materializzato: nessuna sua affermazione è stata verificata eseguendola.

Il sesto è docs/content_taxonomy_bridge.md: la tabella che assegna a ciascuna categoria del catalogo video un profilo di mood su tre assi, e il documento che dichiara come è stata costruita. Sono gli unici valori del progetto che nessuna fonte osserva e nessuna formula calcola: sono assegnati. Il metodo è in quattro passi, ordinati: il criterio di assegnazione (docs/mood_assignment_criteria.md) è scritto e committato prima che qualunque valore esista, un modello linguistico propone in una sola invocazione manuale, una seconda sessione di modello verifica riga per riga contro quel criterio e nessun altro metro, e l'esito si congela in data/curated/ con un numero di versione.

Il settimo è docs/kpi_operators.md: per ciascuno degli 8 KPI, l'operatore analitico con cui la misura verrà calcolata: formula, grana, tabelle da cui legge, confidenza ereditata, limiti dichiarati e le nove decisioni analitiche che quelle regole hanno richiesto di prendere, ciascuna con l'opzione scartata e la ragione dello scarto. Non contiene alcun valore dei KPI: ogni cifra che vi compare è un input già ancorato da una feature precedente.

L'ottavo è docs/kpi_measures.md: il valore di ciascuno degli 8 KPI, la formula DAX con cui la misura si scrive nel modello, la provenienza di ogni numero e i limiti che quel numero porta con sé. È il primo documento del progetto in cui una cifra pubblicata è un risultato e non un input ereditato da una feature precedente. I valori non sono letti a schermo e ricopiati: li calcola scripts/build_kpi_measures.py, uno script deterministico che applica le stesse regole del modello dati e degli operatori sugli stessi dati, perché chi clona il repository senza una licenza Power BI possa comunque rigenerarli.

Il nono deliverable è il primo che non è un documento: la dashboard Power BI in cui gli 8 KPI vanno a schermo, su quattro pagine con la propria navigazione. Il .pbix non è versionato quindi ciò che il repository contiene non è il file ma i due artefatti che lo rendono ispezionabile da chi non può aprirlo: il contratto di pagina, che disegna ogni pagina prima che lo strumento venga aperto e motiva ogni visuale contro la forma del dato, e l'esito della costruzione, che dichiara che cosa esiste davvero e in che cosa differisce dal disegno.

Costruire ha prodotto tre difetti che nessun controllo del repository poteva vedere, tutti in impostazioni che vivono solo dentro il file binario: due sono stati corretti durante la costruzione, il terzo è la tipizzazione già nota alla 007b. Il file è leggibile, non pubblicabile. La feature 008b ha portato a schermo trentadue blocchi di narrazione. Poi ha dichiarato il file pubblicabile, e la revisione in contesto pulito ha risposto di no: venticinque rilievi che ne testimoniano la scarsa leggibilità per un decisore che non ha letto alcun documento di questo repository. La dichiarazione di pubblicabilità è stata ritirata. Il deliverable non viene rifinito perché è stato superato.

Il decimo è docs/raccomandazione.md. Il business case aveva fissato e pubblicato, prima che qualunque numero esistesse, una regola di decisione a tre condizioni e la lettura di ciascun esito; questa feature fissa l'operatore che mancava a una delle tre, calcola il verdetto e lo ancora come qualunque altro valore. Tutte e tre sono soddisfatte, e l'esito è quello che il business case legge come argomento di coerenza sostenuto: l'espansione è possibile.

Gli otto documenti che pubblicano misure — l'audit, il cleaning, gli scenari, il modello, il ponte fra tassonomia e mood, gli operatori, le misure e la raccomandazione — legano ogni numero all'artefatto che lo produce con la stessa grammatica, definita in docs/convenzioni-marcatura.md e verificata da scripts/check_audit_coherence.py. Lo stesso controllo presidia la tassonomia: se le categorie del catalogo video e quelle della tabella dei mood divergessero, fallisce invece di avvisare.

Setup

# 1. Dati raw (non versionati — vedi data/README.md)
./scripts/download_data.sh

# 2. Profilo dei dataset di origine (richiede i dati raw del passo 1)
python3 scripts/profile_data.py

# 3. Pipeline di trasformazione: scrive i quattro dataset in data/processed/
#    e il rendiconto reports/cleaning_report.json (richiede i dati raw)
python3 scripts/build_datasets.py

# 4. Scenari BQ3 dal benchmark congelato (NON richiede i dati raw né rete)
python3 scripts/build_bq3_scenarios.py

# 5. Misure degli 8 KPI, le tre condizioni della regola di decisione e il
#    verdetto, dai dataset trasformati (richiede data/processed/)
python3 scripts/build_kpi_measures.py

# 6. Coerenza fra gli otto documenti pubblicati e i sei artefatti versionati,
#    più il presidio sulla tassonomia delle categorie (NON richiede i dati raw)
python3 scripts/check_audit_coherence.py

Nessuna dipendenza da installare: gli script usano la sola libreria standard di Python 3. Il passo 6 funziona su una copia del repository priva di data/raw/, perché confronta soltanto artefatti versionati — è il modo in cui chi non ha i dati di origine verifica che i numeri dei documenti non siano stati scritti a mano.

Non esiste un passo che rigeneri i profili di mood, e non è un'omissione: quei valori sono assegnati, non calcolati, e nessuno script li tocca dopo il congelamento.

Non esiste nemmeno un passo che rigeneri la dashboard. Il .pbix si costruisce a mano in Power BI Desktop a partire da data/processed/, ed è il confine dell'automazione che la constitution traccia. Le istruzioni sono il contratto di pagina per il modello e le pagine, e il contratto di narrazione per il testo a schermo; ciò che va riverificato a ogni riapertura del file — tipizzazione, lettura dei CSV, colonne di scenario — è elencato nell'esito della costruzione e nell'issue #20.

Quella dashboard viene sostituita, e il disegno di ciò che prende il suo posto è già scritto. La revisione in contesto pulito della 008b l'ha respinta sul metro che la feature si era data — «un decisore che non conclude niente non ha usato la dashboard, l'ha archiviata» — e il difetto non era il testo a schermo: quattro pagine, una per domanda di business, sono un inventario di misure. La 009 ha pubblicato l'argomento che mancava; la 010a lo impagina nel contratto di pagina, che disegna dieci pagine ordinate come l'argomento e non come il framework di KPI: la domanda, la risposta, perché regge, con che cosa entrare, quanto vale, che cosa la ribalterebbe, che cosa non si può concludere. Il contratto dichiara per ciascuna pagina i valori con la propria ancora, le misure distinte fra esistenti e da creare, le visuali con tipo e assi, e le interazioni che non vanno offerte. Nessuna riga descrive il .pbix: è un vincolo su ciò che deve esistere, e la costruzione è della 010b.

Struttura

.specify/       # Spec Kit: constitution, template, script
.claude/        # comandi /speckit.* per Claude Code
.github/        # prompt /speckit.* per GitHub Copilot
data/           # raw / interim / processed (gitignored) + benchmarks/ e curated/ (versionate: non riproducibili)
docs/           # i documenti pubblicati: business case, audit, cleaning, scenari, modello dati,
                #   criterio di mood, ponte tassonomia-mood, operatori delle misure,
                #   misure dei KPI, raccomandazione, convenzioni
reports/        # artefatti versionati: profilo, rendiconto delle trasformazioni, scenari BQ3 e
                #   misure dei KPI (generati) + esito del confronto col motore DAX (curato a mano)
scripts/        # utility riproducibili
specs/          # una cartella per feature: spec.md, plan.md, tasks.md, review.md,
                #   contracts/ dove la feature ne pubblica uno (007a, 007b, 008a, 008b, 009, 010a)

Dati

Due dataset pubblici Kaggle (Spotify tracks + catalogo Netflix). Provenienza e licenze: data/README.md.

Licenza

MIT — codice e documentazione. I dataset raw restano soggetti alle rispettive licenze d'origine (vedi data/README.md).