| name | tracking-plan |
| description | Rédige/actualise le plan de tracking Matomo métier (events/TRACKING_PLAN.md) sous forme de document explicatif (prose + tableaux commentés), à partir du catalogue events.extracted.json et du code frontend. À lancer après toute évolution du tracking. |
| argument-hint | [--skip-extract] |
| allowed-tools | ["Bash","Read","Write","Grep","Glob","Agent"] |
Plan de tracking Matomo — génération du document métier
Tu es un agent spécialisé dans la rédaction du plan de tracking Matomo du projet
Code du travail numérique, à destination du métier (non technique).
Ton livrable est un document explicatif rédigé — pas un simple listing. Tu combines :
- le catalogue exact des events extraits du code (
events.extracted.json, source de
vérité machine), et
- la lecture du code frontend (simulateurs et leurs étapes, parcours convention
collective, recherche entreprise) pour expliquer quand et pourquoi chaque event
est envoyé, avec les vrais titres et étapes.
Un algorithme ne peut produire ce document : il faut comprendre le domaine. C'est ton rôle.
Configuration
- Package stats :
packages/code-du-travail-stats
- Catalogue (entrée) :
packages/code-du-travail-stats/events/events.extracted.json
- Document (sortie) :
packages/code-du-travail-stats/events/TRACKING_PLAN.md
- Frontend :
packages/code-du-travail-frontend/src/modules
- Fichiers d'ancrage à lire (émetteurs et enums de référence) :
analytics/types.ts — enums des category / action (source des libellés métier :
MatomoBaseEvent, MatomoSearchAgreementCategory, MatomoSimulatorEvent,
MatomoAgreementEvent, MatomoActionEvent…).outils/common/components/SimulatorLayout/tracking.ts — events génériques des
simulateurs (arrivée view_step_<sim>, étape précédente click_previous_<sim>,
impression, name = étape courante).outils/common/events/pushAgreementEvents.ts — events de l'étape convention
collective (parcours p1/p2/p3, cc_search, enterprise_search, enterprise_select,
cc_select_p1/p2, cc_select_traitée/non_traitée, user_blocked_info_cc).convention-collective/tracking.ts, enterprise/EnterpriseAgreementSearch/tracking.ts.- Étapes par simulateur :
outils/<simulateur>/steps/** (noms de dossiers = étapes) et le
composant outils/<simulateur>/*Simulator.tsx.
Arguments
$ARGUMENTS peut contenir :
--skip-extract : ne relance pas l'extraction du catalogue (utilise le
events.extracted.json déjà committé). Par défaut, on régénère d'abord le catalogue.
Étapes
1. Rafraîchir le catalogue (sauf --skip-extract)
pnpm -F @socialgouv/cdtn-stats events:extract
Puis lis packages/code-du-travail-stats/events/events.extracted.json. Ce fichier fait
autorité : tout event mentionné dans le document doit exister dans ce catalogue. Ne jamais
inventer une category/action/name absente du catalogue.
Structure d'un event (cf. events.schema.ts) :
category, action, name_pattern (null ou placeholder <…> si calculé au runtime),resolution : "literal" | "enum-param" (valeur fixe → 📌) | "dynamic" (valeur
variable → 🔀),file, line (pour le lien source), tracking_method (sendEvent ou push:<cmd>).- Racine :
total_events, unique_events, matomo_config_calls (commandes de config, pas
des events → annexe), unresolved (à signaler si non vide).
2. Comprendre le domaine (lecture du frontend)
Lis les fichiers d'ancrage listés en Configuration pour reconstituer, avec les vraies
valeurs du code :
- La liste des simulateurs et leurs étapes : pour chaque dossier
outils/<simulateur>
qui a un *Simulator.tsx, récupère le titre affiché (celui utilisé dans view_step_<titre>)
et l'ordre des étapes (dossiers sous steps/ et/ou tableau d'étapes du composant). Recoupe
avec les actions view_step_* du catalogue.
- Les events génériques des simulateurs (arrivée, étape suivante, étape précédente,
impression) depuis
SimulatorLayout/tracking.ts.
- L'étape convention collective (parcours p1/p2/p3 et sous-events) depuis
pushAgreementEvents.ts + convention-collective/tracking.ts + enterprise/**.
Lance ces lectures en parallèle avec des agents Explore si utile (performance).
3. Rédiger events/TRACKING_PLAN.md
Écris le fichier en suivant exactement la structure ci-dessous (« Sortie attendue »), en
remplaçant les placeholders par les vraies données. Le ton est métier, en français,
pédagogique. Le document doit être explicatif : pour chaque event, donne une explication
« quand / pourquoi » (le déclencheur : clic, chargement, erreur, action utilisateur vs clic
« suivant » ; et l'intérêt métier de la mesure). Dans les tableaux par feature, réserve une
colonne « Quand / pourquoi ». Ne te contente jamais de lister l'event sans l'expliquer.
Contraintes de rendu (le fichier finit sur le wiki GitHub) :
- Pas de titre H1 en tête (la page wiki fournit le titre). Commence par le commentaire
HTML de génération puis
## Liste des events de tracking:.
- Les valeurs contenant
<…> (placeholders dynamiques) doivent être en code-span
(`<url>`), sinon GitHub les masque comme des balises HTML.
- Échappe les
| à l'intérieur des cellules de tableau (\|).
- Repère 📌 = valeur fixe, 🔀 = valeur variable (d'après
resolution).
- Ne documente pas les
matomo_config_calls (push de configuration : consentement, heatmap,
referrer) — ce ne sont pas des events de suivi, on ne les liste pas dans ce plan métier.
- Si
unresolved est non vide, signale-le en note (« callsites non résolus » à revoir).
4. Vérifier
- Relis ton document : chaque tableau d'event correspond bien à une entrée du catalogue ;
les simulateurs et étapes correspondent au code ; aucun event inventé.
- Rappelle à l'utilisateur que la sync wiki se fait automatiquement au merge sur
dev (le
workflow stats-events-wiki.yml met à jour le bloc entre marqueurs de la page wiki).
- Ne crée pas de commit automatiquement ; laisse l'utilisateur relire puis committer.
Sortie attendue (structure canonique)
Reproduis fidèlement cette structure. Les libellés d'exemple (Indemnités de licenciement,
étapes, IDCC…) sont des placeholders : mets les valeurs réelles issues du catalogue et du
code. Les sections par feature (recherche, home, thèmes, contributions, courriers, layout,
common…) sont générées à partir du catalogue, une sous-section par catégorie Matomo, avec un
court paragraphe d'explication puis un tableau Action | Name | 📌/🔀 | Code.
<!-- Plan de tracking métier — rédigé via le skill Claude `/tracking-plan`
(packages/code-du-travail-stats). Ne pas éditer à la main : régénérer via le skill
après toute évolution du tracking. Source : events/events.extracted.json + code frontend. -->
## Liste des events de tracking:
#### tracking générique (automatique sur chaque page)
Lors d'une visite sur une page du site, par défaut Matomo envoie un évènement de visite, qui
contient des informations (le nom de la page et son url).
Exemple d'information envoyé suite à une visite sur la page des thèmes :
| Type | Donnée | Info |
| ----------- | ---------------------------------- | ---------------------------------------- |
| action_name | Thèmes - Code du travail numérique | Titre de la page |
| url | https://code.travail.gouv.fr/themes | Lien vers la page |
| urlref | / | Origine de l'utilisateur (ici l'accueil) |
### Outils
#### Simulateurs
Voici la liste des simulateurs disponibles (avec leurs étapes) :
| Titre | Étapes |
| --------------------------- | ---------------------------------------------------------------- |
| <Nom du simulateur> | <étape_1>, <étape_2>, … |
##### Évènements génériques sur les simulateurs
Pour chaque simulateur, on envoie des évènements génériques.
###### Arrivée sur l'outil
| Type | Contenu | Détail |
| -------- | --------------------------- | --------------------------------------------------------- |
| category | outil | |
| action | view_step_`Nom du simulateur` | `Nom du simulateur` = titre du simulateur |
| name | start | |
###### Étape suivante
| Type | Contenu | Détail |
| -------- | --------------------------- | -------------------------------------------------- |
| category | outil | |
| action | view_step_`Nom du simulateur` | `Nom du simulateur` = titre du simulateur |
| name | Nom de l'étape | L'étape sur laquelle l'utilisateur est arrivé |
###### Étape précédente
| Type | Contenu | Détail |
| -------- | ------------------------------- | ----------------------------------------------- |
| category | outil | |
| action | click_previous_`Nom du simulateur` | `Nom du simulateur` = titre du simulateur |
| name | Nom de l'étape | L'étape sur laquelle l'utilisateur est revenu |
###### Étape pour renseigner sa convention collective
Cette étape n'est pas présente sur tous les simulateurs. Les events sont divisés en 2 : ceux
envoyés sur **l'action de l'utilisateur**, et ceux envoyés **au clic sur suivant** (non envoyés
en cas d'erreur de saisie). Trois parcours :
* **p1** : je connais ma convention collective (je la saisis)
* **p2** : je ne la connais pas (je recherche mon entreprise)
* **p3** : je ne souhaite pas la renseigner (je passe l'étape)
1. Choix du parcours (**envoyé au clic sur suivant**)
| Type | Contenu | Détail |
| -------- | ------------------------------------ | ----------------------------------- |
| category | cc_search_type_of_users | |
| action | click_p1 ou click_p2 ou click_p3 | Selon le parcours (p1, p2, p3) |
| name | `Nom du simulateur` | Titre du simulateur |
2. Recherche (**envoyé sur action de l'utilisateur**, debounce 300 ms)
| Type | Contenu | Détail |
| -------- | --------------------- | ---------------------------------------------------- |
| category | cc_search | Recherche d'une convention collective (parcours p1) |
| action | `Nom du simulateur` | Titre du simulateur |
| name | {"query":"boulan"} | JSON du contenu de la requête utilisateur |
| Type | Contenu | Détail |
| -------- | -------------------------------- | ----------------------------------------- |
| category | enterprise_search | Recherche d'une entreprise (parcours p2) |
| action | `Nom du simulateur` | Titre du simulateur |
| name | {"address":"69007","query":"odon"} | JSON du contenu de la requête |
3. Choix de l'entreprise, parcours p2 (**envoyé au clic sur suivant**)
| Type | Contenu | Détail |
| -------- | ------------------- | ----------------------------------------- |
| category | enterprise_select | |
| action | `Nom du simulateur` | Titre du simulateur |
| name | {"label":"…","siren":"…"} | Entreprise sélectionnée |
4. Choix de la convention collective (**envoyé au clic sur suivant**)
| Type | Contenu | Détail |
| -------- | ------------------------------ | ----------------------------------------- |
| category | cc_select_p1 ou cc_select_p2 | Selon le parcours choisi |
| action | `Nom du simulateur` | Titre du simulateur |
| name | idcc1234 | IDCC choisi, préfixé `idcc` |
5. Support de la convention collective (**envoyé au clic sur suivant**)
| Type | Contenu | Détail |
| -------- | ------------------------------------------- | -------------------------------------------- |
| category | outil | |
| action | cc_select_traitée ou cc_select_non_traitée | La CC est traitée par nos services ou non |
| name | 1234 | IDCC de la convention collective |
6. CC bloquantes (simulateurs où la CC est obligatoire)
| Type | Contenu | Détail |
| -------- | -------------------------------------------- | ---------------------------------- |
| category | outil | |
| action | view_step_`Nom du simulateur` | Simulateur concerné |
| name | user_blocked_info_cc | |
### <Autre feature (ex: Recherche, Accueil, Thèmes, Contributions, Modèles de courriers…)>
<Un paragraphe expliquant le contexte de ces events.>
| Catégorie | Action | Name (📌/🔀) | Quand / pourquoi | Code |
| --------- | ------ | ------------ | ---------------- | ---- |
| <category> | `<action>` | 📌 `<name ou —>` | <déclencheur + intérêt métier, 1 phrase> | [↗](https://github.com/SocialGouv/code-du-travail-numerique/blob/dev/<file>#L<line>) |
> Signale à part, en note, les events **définis dans le code mais non branchés** en production
> (fonction jamais appelée par un composant) : ils sont dans le catalogue mais n'ont pas de
> déclencheur utilisateur réel aujourd'hui.
Ne pas ajouter d'annexe des matomo_config_calls : les commandes de configuration
(consentement, heatmap, referrer) ne sont pas des events de suivi et n'ont pas leur place dans
ce plan métier.
Règles de mapping (catalogue → tableaux)
resolution : literal/enum-param → 📌 (valeur fixe) ; dynamic → 🔀
(valeur variable, représentée par un placeholder <…>).name_pattern = null → afficher —. Les <…> → toujours en code-span.- Liens
Code : https://github.com/SocialGouv/code-du-travail-numerique/blob/dev/<file>#L<line>
(branche fixe dev, URL absolue → valide dans le repo ET le wiki).
- Enums d'
action/category : utilise analytics/types.ts pour donner le libellé
métier (ex. cc_select_traitée = « CC traitée par nos services »).
view_step_<X> / click_previous_<X> : <X> est le titre du simulateur (suffixe
ajouté au runtime). Les regrouper dans la partie « Simulateurs », pas en doublon par feature.matomo_config_calls → ne pas documenter (ce ne sont pas des events de suivi).
Bonnes pratiques
- Exhaustivité vérifiée : couvre tous les events. Après rédaction, recoupe le document
avec le catalogue (chaque catégorie et chaque action littérale doit apparaître) ; en mode
Product Owner, assure-toi qu'aucun event n'est oublié.
- Une explication par event : « quand / pourquoi ». Distingue « émis sur action utilisateur »
et « émis au clic sur suivant » quand les deux existent.
- Collapse des expansions enum-param : quand un même motif est décliné par simulateur (ex.
cc_select_p1/p2, enterprise_select dont l'action = titre du simulateur, ou les 4 motifs
de feedback_category), regroupe en une ligne « motif », pas 5–8 doublons.
- Zéro invention : chaque event du document existe dans
events.extracted.json. En cas de
doute, relis le catalogue, ne devine pas.
- Vraies valeurs : simulateurs, étapes, IDCC d'exemple → tirés du code, pas des exemples de
ce gabarit.
- Métier d'abord : privilégie l'explication (« quand part cet event, pourquoi ») aux
détails techniques. Les tableaux portent les valeurs exactes.
- Déterminisme des liens : toujours pointer sur
dev (jamais un SHA).
- Ne pas committer automatiquement : laisser l'utilisateur relire puis committer
events/TRACKING_PLAN.md (et events/events.extracted.json s'il a changé).
- Pas de drift-check sur ce fichier : c'est un document rédigé. Après une évolution du
tracking, relance ce skill pour le tenir à jour.
