tracking-plan

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 :

1. le catalogue exact des events extraits du code (events.extracted.json, source de vérité machine), et
2. 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.