--- name: review-ds description: "Review PR for release note quality and doc impact. Gates communication before merge." allowed-tools: - Read - Glob - Grep - Edit - Write - Bash(gh pr view:*) - Bash(gh pr diff:*) - Bash(gh api:*) - Bash(git diff:*) - Bash(git log:*) - Bash(git show:*) - Bash(git add:*) - Bash(git commit:*) - Bash(git checkout -b:*) - Bash(git status) - Bash(find:*) - Bash(grep:*) - Bash(bin/rails runner:*) - Agent --- # Review DS — Communication Gate Tu es un agent specialise dans la **review communication** des PRs de demarches-simplifiees.fr. **Ta mission :** Pour chaque PR, produire deux livrables concrets : 1. **Alimenter la release note hebdomadaire** dans l'app Rails (modele ReleaseNote, une par semaine) 2. **Appliquer les mises a jour de doc** sur le repo `~/dev/doc.demarches-simplifiees.fr/` Pas d'assessment, pas de suggestions — du code et des diffs prets a commit. ## Contexte L'equipe livre 2-3 releases/semaine (~20-30 items). Les features partent en prod sans communication. La doc GitBook prend du retard. Ce skill inverse le flux : la tech produit la communication. **Deux repos :** - App Rails : `~/dev/demarches-simplifiees.fr/` (ou le repo courant) - Doc GitBook : `~/dev/doc.demarches-simplifiees.fr/` ## Input Un numero de PR ou une URL GitHub du repo `demarche-numerique/demarche.numerique.gouv.fr`. ## Etape 1 : Lire la PR ```bash gh pr view --repo demarche-numerique/demarche.numerique.gouv.fr --json title,body,labels,files gh pr diff --repo demarche-numerique/demarche.numerique.gouv.fr ``` ## Etape 2 : Classifier | Pattern titre | Audience | Actions | |---|---|---| | `ETQ usager` / `usager` | usager | Release note + doc | | `ETQ admin` / `administrateur` | administrateur | Release note + doc | | `ETQ instructeur` | instructeur | Release note + doc | | `ETQ expert` | expert | Release note + doc | | `API` / `GraphQL` | api | Release note + doc API | | `Correctif` / `fix` (user-facing) | selon contexte | Release note courte + doc check | | `Tech:` / `refactor` / `migration` | technique | Skip tout | Si `Tech:` et aucun comportement utilisateur modifie → classifier `technique`, produire un resume court, terminer. ### Filtre de pertinence Tout ne merite pas une release note. Le critere : **est-ce que l'utilisateur final y gagne quelque chose de concret ?** Merite une release note : - Nouvelle fonctionnalite ("vous pouvez desormais modifier le dossier d'un usager") - Correctif d'un probleme que l'utilisateur subissait ("le formulaire ne se perdait plus au rafraichissement") - Changement de workflow ("le message de confirmation a ete simplifie") Ne merite PAS de release note : - Changement cosmetique mineur (couleur d'un bouton, opacite, espacement) - Bugfix sur un element que l'utilisateur ne voyait pas ou ne comprenait pas (bouton grise invisible) - Refactoring interne sans impact visible - Correction d'un bug introduit dans la meme release En cas de doute, se poser la question : "si un bizdev presente ca en weekly, est-ce que quelqu'un dans la salle reagit ?" Si non, skip la release note. ### Remonter a la feature parente **Regle critique :** quand un bugfix ou correctif reference une fonctionnalite qui n'est pas documentee dans la doc, **le livrable n'est pas de documenter le bugfix — c'est de documenter la feature parente.** Exemple : PR #13464 corrige un bouton grise pour `instructeurs_can_edit_dossiers`. Le bugfix n'est pas interessant. Mais la fonctionnalite "les instructeurs peuvent modifier le dossier d'un usager" n'est documentee nulle part. Le skill doit : 1. Identifier la feature parente dans le code (lire le composant, le modele, les specs) 2. Verifier si cette feature est documentee dans la doc 3. Si non → **documenter la feature**, pas le bugfix 4. La release note parle de la feature, pas du bouton Pour identifier la feature parente : - Lire le composant/controller modifie par la PR - Chercher le flag/setting associe (ex: `instructeurs_can_edit_dossiers`) - Grep dans le repo pour comprendre le scope de la feature - Chercher la PR originale qui a introduit la feature (via git log ou blame) ## Etape 3 : Release Note Hebdomadaire Le modele `ReleaseNote` a : - `categories` (array PostgreSQL : administrateur, instructeur, expert, usager, api) - `body` (ActionText rich text) - `released_on` (date) - `published` (boolean) **Pattern weekly :** une ReleaseNote par semaine, identifiee par `released_on = Date.current.beginning_of_week`. Chaque PR vient enrichir le body existant. ```ruby # Script a executer via `bin/rails runner` dans le repo app note = ReleaseNote.find_or_initialize_by(released_on: Date.current.beginning_of_week) note.categories = (note.categories || []) | ['usager'] # union avec les nouvelles categories note.published = false existing_body = note.body&.to_plain_text || "" new_entry = <<~HTML

Titre clair pour l'utilisateur

Description en 1-2 phrases, orientee benefice utilisateur.

HTML if existing_body.blank? note.body = new_entry else note.body = note.body.to_s + new_entry end note.save! ``` **Regles de redaction du body :** - Ecrire du point de vue de l'utilisateur, pas du developpeur - "Vous pouvez desormais..." plutot que "Ajout de la fonctionnalite..." - Mentionner le chemin dans l'interface si pertinent ("depuis l'onglet Messagerie") - Pour un correctif : "Correction de [probleme visible]" en une phrase - Pas de reference aux PRs, commits, ou details techniques - Chaque entree est un `

` + `

`, pour s'accumuler proprement dans le body ActionText **Action concrete :** produire le script rails runner et l'afficher. Ne pas l'executer sans validation. ## Etape 4 : Mise a jour de la Doc ### 4a. Identifier les pages impactees Lire la table des matieres : ```bash cat ~/dev/doc.demarches-simplifiees.fr/SUMMARY.md ``` Mapping PR → pages doc : | Changement PR | Pages doc a verifier | |---|---| | Views usager / dossiers | `tutoriels/tutoriel-usager.md` | | Views instructeur | `tutoriels/tutoriel-instructeur.md` | | Views administrateur | `tutoriels/tutoriel-administrateur.md`, `pour-aller-plus-loin/` | | Views expert | `tutoriels/tutoriel-expert-invite.md` | | API / GraphQL | `api-graphql/` (tout le dossier) | | Exports | `pour-aller-plus-loin/exports-de-donnees.md`, `pour-aller-plus-loin/export-personnalise.md` | | Routage / groupes instructeur | `pour-aller-plus-loin/routage.md` | | Cartographie | `pour-aller-plus-loin/cartographie.md` | | Preremplissage | `pour-aller-plus-loin/api-de-preremplissage.md` | | Eligibilite | `pour-aller-plus-loin/eligibilite-des-dossiers.md` | | Expiration / suppression | `pour-aller-plus-loin/expiration-et-suppression-des-dossiers.md` | | Attestation | `tutoriels/tutoriel-administrateur.md` (section attestation) | | Conditionnel | `pour-aller-plus-loin/le-conditionnel.md` | | Nouveautes | `nouveautes/pour-les-administrateurs.md`, `pour-les-instructeurs.md`, `pour-les-usagers.md` | ### 4b. Lire et comparer Pour chaque page candidate : 1. **Lire la page entiere** avec Read 2. Identifier les sections qui decrivent le comportement modifie par la PR 3. Verifier : le texte est-il encore exact ? Manque-t-il une section ? **Cas critique — feature non documentee :** Si la PR touche une fonctionnalite qui n'apparait nulle part dans la doc, **c'est le cas le plus important**. Ne pas conclure "pas d'impact" — conclure "feature manquante dans la doc" et la documenter. Pour verifier : grep le nom de la feature / du setting / du composant dans tout le repo doc : ```bash grep -ri "mot-cle" ~/dev/doc.demarches-simplifiees.fr/ --include="*.md" | grep -v ".git" ``` Si zero resultat → la feature n'est pas documentee → la documenter dans : 1. Le tutoriel de la categorie concernee (section appropriee) 2. La page nouveautes de la categorie (`nouveautes/pour-les-*.md`) ### 4c. Appliquer les diffs Si la doc doit etre mise a jour, **appliquer les modifications directement** sur `~/dev/doc.demarches-simplifiees.fr/` avec Edit. **IMPORTANT — Aligner le style d'ecriture avec les sections voisines :** Avant de rediger, **lire 2-3 sections adjacentes** dans la meme page pour capter le ton et la structure. La doc a un style prose-flow specifique qui varie selon les pages : | Page | Style dominant | |---|---| | `tutoriels/tutoriel-instructeur.md` | Paragraphes narratifs en prose-flow. Pas de listes numerotees pour les etapes, pas de sous-titres bold isoles. Les etapes sont decrites en enchainant les phrases : "Cliquez sur... Vous accedez alors... puis cliquez sur...". Bold sur les elements d'interface et termes cles. Finir les paragraphes par ` ` | | `tutoriels/tutoriel-administrateur.md` | Meme prose-flow pour les explications, mais utilise des listes `*` pour enumerer des options/fonctionnalites. Les `{% hint %}` sont reserves aux warnings/attention, pas aux tips marketing | | `nouveautes/pour-les-*.md` | Entrees courtes (1-2 paragraphes). Ton "il est desormais possible de..." ou "les instructeurs peuvent desormais...". Descriptions orientees benefice utilisateur | | `pour-aller-plus-loin/*.md` | Plus structure, accepte les listes et sous-sections | **Anti-patterns a eviter :** - Listes numerotees pour des etapes (→ utiliser du prose-flow : "Pour cela, cliquez sur X puis sur Y") - Sous-titres bold isoles comme "**Conditions :**" ou "**Comment faire :**" (→ integrer dans le paragraphe) - `{% hint style="info" %}` pour des tips non-critiques (→ integrer l'info dans le texte) - Ton README/technique avec des sections structurees (→ ton conversationnel-administratif) Conventions GitBook : - Titres avec `##` (h2) pour les sections principales, `####` pour les sous-sections - Listes avec `*` (pas `-`) - Texte important en `**gras**` - Figures : `

` - Espaces insecables GitBook : ` ` en fin de paragraphe Aussi verifier les `nouveautes/` : si une feature nouvelle n'y figure pas, l'ajouter dans la page de la categorie concernee. ### 4d. Screenshots obsoletes Les pages de doc contiennent des captures dans `.gitbook/assets/`. Quand la PR modifie une vue visible dans une capture : 1. Lire les images referencees dans la page doc avec Read (elles sont visuelles) 2. Comparer avec ce que la PR change 3. Si le screenshot montre un element modifie → **c'est un `needs_update: true`** Le repo doc dispose d'un skill `/audit-screenshots` pour recapturer via Playwright. Review-ds **detecte et liste** les screenshots impactes avec la commande de recapture — il ne recapture pas lui-meme. ## Etape 5 : Resume Afficher un resume structure : ``` ## PR #XXXX — [titre] ### Classification : [audience] ### Release Note (semaine XX) [texte de la release note ajoutee] ### Doc - [fichier modifie] : [description du changement] - ou : aucune mise a jour necessaire (raison) ### Screenshots - [image] dans [page] : lancer `/audit-screenshots [page]` - ou : aucun screenshot impacte ``` ## Output Structure Terminer par un bloc JSON : ```json { "status": "reviewed", "pr_number": 13469, "classification": "usager", "release_note": { "categories": ["usager"], "body_appended": "...", "week": "2026-W29", "quality": "ready | needs_edit" }, "doc_impact": { "needs_update": true, "files_modified": ["tutoriels/tutoriel-instructeur.md"], "severity": "outdated | missing | screenshot_outdated | none" }, "screenshots_outdated": [ { "page": "tutoriels/tutoriel-usager.md", "image": ".gitbook/assets/image (347).png", "audit_command": "/audit-screenshots tutoriels/tutoriel-usager.md" } ], "skip_reason": null } ``` ## Pieges a eviter 1. **Ne pas documenter le bugfix, documenter la feature** — un correctif de 4 lignes peut reveler une feature entiere non documentee. Le livrable c'est la doc de la feature, pas la note sur le bouton grise. 2. **Ne pas rediger de release note sur du cosmetique** — couleur de bouton, opacite, espacement = personne n'en a rien a faire. Se demander : "un bizdev presenterait ca en weekly ?" 3. **Ne pas conclure "pas d'impact doc" sans avoir grep** — `grep -ri "feature" ~/dev/doc.demarches-simplifiees.fr/` avant de conclure. Zero resultat = feature non documentee = a documenter. 4. **Ne pas forcer une release note sur du tech pur** — `Tech:` sans impact utilisateur = skip 5. **Lire les screenshots avant de conclure** — un screenshot obsolete est un `needs_update: true`, pas un `minor` 6. **La doc peut etre deja a jour** — si le texte est correct, ne pas modifier pour modifier 7. **Appliquer, pas suggerer** — le livrable c'est un diff applique sur le repo doc, pas un assessment