pr-explainer — expliquer la PR en une page HTML

Sortie : un fichier HTML autonome dans .pr-review/ (ignoré par git) qu'un relecteur peut ouvrir localement et comprendre la PR sans GitHub. Il complète la vraie revue de diff ; il ne la remplace jamais.

Annonce au démarrage : « Using the pr-explainer skill — building the review page for {branch}. »

Étape 1 : Rassembler les faits (avant d'écrire du HTML)

BASE=$(git merge-base origin/main HEAD)
git status --short                      # current state
git log --oneline $BASE..HEAD           # the commits
git diff $BASE...HEAD --stat            # scope + the metrics numbers
git diff $BASE...HEAD                   # read the whole diff
gh pr view --json number,title,url 2>/dev/null   # if a PR exists

Collectez aussi : les vérifications déjà effectuées cette session (exécutions de tests, vérifications en navigateur, captures d'écran) — la page doit rapporter des preuves réelles, pas des aspirations.

Étape 2 : Classifier les fichiers et trouver l'ordre pédagogique

Classifiez chaque fichier modifié : comportement central · plomberie/intégration · tests · métadonnées/release · bruit incident. Seul le comportement central et la plomberie portante reçoivent des sections de walkthrough ; les autres reçoivent au maximum une ligne.

Enseignez dans cet ordre (jamais l'ordre brut du diff) : problème → contexte système → flux avant/après → changements de code clés → vérification → conclusion pour le relecteur.

Étape 3 : Remplir le template

mkdir -p .pr-review
cp .ai/skills/pr-explainer/assets/template.html .pr-review/{branch}.html

Le template a une section par étape pédagogique, stylisée et prête — chaque endroit à remplir est marqué avec un commentaire <!-- FILL: ... -->. Travaillez de haut en bas :

1. En-tête : numéro PR/titre/branche/lien ; métriques de --stat (vrais chiffres).
2. Problème : comportement antérieur et pourquoi il était faux/manquant/risqué, avec un exemple concret.
3. Contexte système : appelants en amont, effets en aval, pourquoi cette couche ; nommez ce qui est intentionnellement inchangé.
4. Flux avant → après : dupliquez les lignes .flow, marquez les nœuds modifiés avec class="node hot". Supprimez la section si la PR ne change aucun flux. Mettez le fait contre-intuitif dans la callout.
5. Walkthrough du code : un bloc .diff par fichier important — uniquement les lignes pertinentes (spans .add / .del / .ctx), chacune suivie d'un court paragraphe : ce qu'elle accomplisse et comment elle se connecte à l'histoire.
6. Tests & vérification : commandes exactes exécutées et leurs résultats. Si une vérification n'a pas été exécutée, dites-le et listez la commande recommandée — ne jamais sous-entendre une vérification qui n'a pas eu lieu.
7. Conclusion pour le relecteur : le modèle mental le plus court et utile + sur quoi se concentrer dans le vrai diff.

Règles de rédaction : langage clair ; définissez les termes spécifiques au repo à première utilisation ; petits snippets ciblés plutôt que patches complets ; supprimez toute section du template qui ne s'applique pas (les sections vides sont du bruit).

Étape 4 : Vérifier et remettre

• [ ] Chaque commentaire <!-- FILL --> est soit rempli, soit sa section supprimée
• [ ] Les métriques correspondent à git diff $BASE...HEAD --stat
• [ ] Chaque affirmation dans Vérification correspond à une commande réellement exécutée
• [ ] Le fichier s'ouvre seul (pas d'assets externes) — c'est un seul fichier HTML
• [ ] .pr-review/ reste non suivi (git status n'affiche rien de stagé depuis celui-ci)

Rapport : le chemin de sortie, l'histoire PR couverte, et tout écart de vérification que la page révèle.