gate-validator - SKILL.md Agent Skill

name: gate-validator description: "Valide les milestones du projet NLP Sentiment Analysis (M0..M6) en vérifiant les critères de sortie, livrables, seuils d'accuracy et conformité spec. À utiliser pour auditer un milestone avant passage au suivant." argument-hint: "[milestone: M0|M1|M2|M3|M4|M5|M6|all] [mode: check|report]"

Agent Skill — Milestone Validator (NLP Sentiment Analysis)

Objectif

Auditer un ou plusieurs milestones du plan d'implémentation et produire un verdict structuré (GO / NO-GO / GO AVEC RÉSERVES) avec preuves.

Contexte repo

Plan : docs/plan/implementation.md
Spécification : docs/specifications/specs.md
Notebook : notebook.ipynb (livrable principal)
Cours : docs/cours/

Rôle de l'agent

Tu dois :

vérifier que les critères de sortie de chaque milestone sont satisfaits ;
confronter chaque critère aux cellules du notebook réellement présentes ;
produire un rapport de conformité factuel (pas d'hypothèses) ;
ne jamais déclarer un milestone GO sans preuve vérifiable.

Registre des milestones

M0 — Fondations & Environnement

#	Critère	Preuve attendue
M0.1	Notebook créé avec squelette 10 sections	Cellules markdown de titre présentes
M0.2	Cellule imports & config exécutable sans erreur	Imports torch, transformers, sklearn, nltk, pandas
M0.3	Seeds de reproductibilité fixées	Fonction `set_seed(seed)` présente et appelée
M0.4	Dataset chargé et exploré	DataFrame avec colonnes `review`, `score`/`sentiment`
M0.5	Distribution des classes visualisée	Graphique de distribution des labels
M0.6	Mapping labels effectué	3 classes : positif (4-5★), négatif (1-2★), neutre (3★)

M1 — Pipeline de données

#	Critère	Preuve attendue
M1.1	Split train/val/test stratifié	Code de split avec `stratify=`, seed fixée
M1.2	Poids de classe calculés	`compute_class_weight('balanced')` sur train
M1.3	Pipeline classique fonctionnel	Fonctions `clean_text()`, `tokenize()`, stop-words
M1.4	Vocabulaire construit sur train uniquement	`word2idx` avec `<PAD>`, `<UNK>`
M1.5	TF-IDF fit sur train	`TfidfVectorizer.fit()` sur train, `transform()` sur val/test
M1.6	DataLoaders classiques opérationnels	Itération sans erreur sur chaque DataLoader
M1.7	Pipeline Transformer fonctionnel	`AutoTokenizer`, `TransformerDataset`, DataLoaders
M1.8	`MAX_SEQ_LEN` déterminé	Analyse distribution longueurs, percentile 95

M2 — Modèle Transformer (PRIORITÉ COMPÉTITION)

#	Critère	Seuil	Preuve attendue
M2.1	Modèle Transformer défini	—	`AutoModelForSequenceClassification` instancié
M2.2	Boucle d'entraînement Transformer	—	Fonction `train_transformer()` opérationnelle
M2.3	Accuracy test ≥ 85%	85%	Métriques calculées et affichées
M2.4	Courbes d'apprentissage	—	Graphiques loss/accuracy par epoch
M2.5	Meilleur modèle sauvegardé	—	`torch.save()` effectué
M2.6	Precision + Confusion Matrix	—	Affichés pour le modèle Transformer

M3 — Baseline & MLP

#	Critère	Seuil	Preuve attendue
M3.1	Logistic Regression entraînée	Accuracy ≥ 60%	Métriques calculées
M3.2	MLP PyTorch défini et entraîné	Accuracy ≥ 65%	Classe `SentimentMLP(nn.Module)` + métriques
M3.3	Courbes d'apprentissage MLP	—	Graphiques

M4 — Modèles pédagogiques

#	Critère	Seuil	Preuve attendue
M4.1	BiLSTM + Attention défini et entraîné	Accuracy ≥ 70%	Classe `BiLSTMAttention` + métriques
M4.2	CNN texte défini et entraîné	Accuracy ≥ 70%	Classe `TextCNN` + métriques
M4.3	Mécanisme d'attention implémenté	—	Module Attention Bahdanau
M4.4	Courbes d'apprentissage	—	Graphiques BiLSTM + CNN

M5 — Évaluation comparative & Prédictions

#	Critère	Preuve attendue
M5.1	Tableau comparatif complet	Accuracy, Precision, Recall, F1 pour tous les modèles
M5.2	Confusion Matrices côte à côte	Visualisation pour chaque modèle
M5.3	Fonction `predict()` pipeline classique	Prend texte brut → retourne prédiction + probabilités
M5.4	Fonction `predict()` pipeline Transformer	Prend texte brut → retourne prédiction + probabilités
M5.5	Tests sur commentaires inédits	Exemples positifs, négatifs, neutres, ambigus
M5.6	Meilleur modèle identifié et documenté	Conclusion argumentée

M6 — Finalisation du notebook

#	Critère	Preuve attendue
M6.1	Toutes les fonctions ont une docstring	Inspection systématique
M6.2	Cellules markdown explicatives	Introduction, transitions, interprétations, conclusion
M6.3	Structure en 10 sections conforme (§10 spec)	Vérification de l'ordre
M6.4	Notebook exécutable de A à Z	Restart & Run All sans erreur
M6.5	Exigences du sujet satisfaites	Precision ✓, Confusion Matrix ✓, PyTorch ✓, Prédictions ✓, Docstrings ✓
M6.6	Notebook nettoyé	Pas de cellules debug, outputs inutiles, code mort

Workflow de validation

Identifier le milestone demandé (ou all pour audit complet).
Parcourir le registre : pour chaque critère, vérifier preuve dans le notebook.
Vérifier l'intégrité des données : vocabulaire/vectorisation fit sur train uniquement.
Vérifier les seuils d'accuracy : comparer aux minimums spécifiés.
Produire le verdict par critère.

Format du rapport de sortie

# Rapport de validation — Milestone [MN]

Date : [YYYY-MM-DD]
Milestone : [M0..M6]
Verdict global : [GO | NO-GO | GO AVEC RÉSERVES]

## Détail par critère

| # | Critère | Verdict | Preuve / Remarque |
|---|---|---|---|
| MN.1 | … | GO | Cellule [N] du notebook |
| MN.2 | … | NO-GO | Absent : [ce qui manque] |

## Actions requises (si NO-GO)
1. [Action corrective 1]
2. [Action corrective 2]

Ordre d'exécution

M0 → M1 → M2 (GO: ≥85%) → M3 → M4 → M5 → M6

M2 est bloquant : ne pas passer à M3/M4 tant que le Transformer ne score pas ≥ 85%.

Principes

Factuel : ne pas inférer de conformité sans preuve tangible.
Traçable : chaque verdict cite la cellule du notebook ou le livrable.
Incrémental : un milestone peut être audité plusieurs fois.
Système de fichiers : toute écriture (rapport) doit rester dans le répertoire du projet (/Users/rousseau/nlp_projet/). Interdit d'écrire dans /tmp, /var ou tout autre chemin hors du projet.