md-review

Présentation de la skill md-review

Ce que fait md-review

md-review est une skill de présentation de Code Review qui transforme un compte rendu de PR en markdown en une revue HTML autonome, sur deux colonnes. Elle attend un markdown de revue contenant des blocs fenced diff au format unified diff, ainsi que des commentaires avec niveau de sévérité, par exemple > [!BLOCKER], > [!MAJOR], > [!MINOR] ou > [!NIT]. Le résultat affiche le diff rendu à gauche, les cartes d’annotation à droite, une navigation de saut vers les findings en haut de page, ainsi qu’un pied de page obligatoire avec le nom du reviewer.

Utilisateurs et workflows les plus adaptés

La skill md-review convient surtout aux équipes qui rédigent déjà des notes de code review structurées en markdown et veulent produire un artefact HTML portable à partager, archiver ou transmettre hors d’une plateforme de PR. Elle s’adresse aux engineering leads, reviewers, mainteneurs de documentation et workflows agentiques qui convertissent une analyse de PR en page de revue finalisée. Elle est particulièrement utile quand la sévérité des remarques, l’ancrage aux lignes et l’accessibilité comptent davantage qu’un simple résumé markdown.

Ce qui distingue md-review

Contrairement à un prompt générique du type « rends cette review plus jolie », md-review s’appuie sur un pipeline défini : diff_parser.py extrait les hunks unified diff, annotation_extractor.py rattache les callouts de sévérité au bloc diff le plus proche qui les précède, puis review_html_renderer.py produit le HTML final. Le dépôt documente aussi les choix de rendu dans references/diff_rendering_canon.md, references/pr_annotation_ux.md et references/severity_coding.md, ce qui rend la sortie plus prévisible qu’une mise en forme LLM improvisée.

Contraintes clés avant adoption

Le principal point de blocage est la forme de l’entrée. md-review n’est pas destiné aux pages markdown ordinaires, aux release notes ni aux rapports narratifs sans hunks de diff. La skill refuse le rendu sans nom de reviewer explicite, et elle est conçue pour ne pas encoder la sévérité uniquement par la couleur : les badges incluent des icônes et du texte aria-label pour respecter WCAG 1.4.1. Si votre source ne contient pas de vrais unified diffs, orientez plutôt la tâche vers une skill de rendu documentaire.

Utiliser la skill md-review

Installation de md-review et fichiers du dépôt à examiner

Pour les gestionnaires de skills compatibles avec Claude, installez-la depuis le chemin du dépôt GitHub, par exemple :

npx skills add alirezarezvani/claude-skills --skill md-review

Après l’installation, lisez d’abord SKILL.md pour comprendre les règles d’invocation, puis examinez ces fichiers avant de l’utiliser en production :

• scripts/diff_parser.py pour les formats de fenced diff acceptés et --infer-diff
• scripts/annotation_extractor.py pour le parsing des callouts et le comportement de rattachement
• scripts/review_html_renderer.py pour les flags de rendu obligatoires comme --reviewer
• assets/md_review_template.html pour la structure de la page finale
• references/severity_coding.md pour les niveaux de sévérité par défaut et personnalisés

Préparer une entrée que md-review peut parser

Un bon usage de md-review commence par un markdown où chaque finding reste proche du diff qu’il commente :

# Review: payment retry change

```diff
--- a/src/retry.py
+++ b/src/retry.py
@@ -14,6 +14,8 @@ def retry_payment():
-    attempts = 1
+    attempts = 5
+    timeout = None

[!BLOCKER]
This can retry indefinitely if the provider never returns. Add a bounded timeout.

Utilisez des blocs fenced `diff` quand c’est possible. Le parser peut inférer certains blocs non balisés uniquement lorsque `--infer-diff` est utilisé, mais des fences explicites réduisent les ambiguïtés. Placez les commentaires généraux avant tout diff seulement si vous voulez qu’ils soient rendus comme des commentaires non ancrés.

### Invoquer md-review dans un workflow agentique

La skill peut être déclenchée lorsqu’un orchestrateur markdown-html classe l’entrée comme `REVIEW`, ou directement avec `/cs:md-review`. Un prompt complet doit fournir le markdown source, le nom du reviewer et toute modification de convention de sévérité :

```text
/cs:md-review
Convert this markdown code review into a single-file HTML review.
Reviewer: Jane Doe
Use the default BLOCKER/MAJOR/MINOR/NIT severity convention.
Keep all diff hunks and attach annotations to the nearest preceding hunk.
[Paste review markdown here]

Si vous utilisez les scripts directement, le flux pratique est le suivant : parser les blocs diff en JSON, extraire les annotations par rapport à ces hunks, puis générer le HTML avec --reviewer. Les scripts n’utilisent que la stdlib Python, ce qui les rend plus simples à exécuter dans une CI verrouillée ou dans une automatisation locale.

Conseils pratiques pour améliorer la qualité de sortie

Pour un meilleur ancrage, placez chaque callout immédiatement après le bloc diff concerné. Pour faciliter le triage, réservez BLOCKER aux problèmes qui doivent impérativement être corrigés et évitez de classer chaque sujet en MAJOR. Pour une meilleure lisibilité au scan, rédigez la première phrase de chaque annotation comme le point de décision, car la navigation de saut utilise de courts aperçus. Si votre équipe utilise d’autres libellés, passez une convention personnalisée à quatre niveaux, du plus sévère au moins sévère, par exemple critical,important,suggestion,nit.

FAQ de la skill md-review

md-review est-elle uniquement destinée à la Code Review ?

Oui. md-review pour Code Review est volontairement ciblée : elle convertit des reviews de PR en markdown, avec hunks de diff et annotations de sévérité, en page de revue HTML. Ce n’est ni un générateur de site markdown généraliste, ni un générateur de diff de PR, ni un substitut à la rédaction de la review elle-même.

Que se passe-t-il si mon markdown ne contient aucun bloc diff ?

C’est un mauvais cas d’usage. La mise en page centrale de la skill dépend des unified diff hunks, des numéros de ligne, des ajouts, des suppressions et du rattachement des annotations. Sans blocs diff, le résultat serait trompeur ; le comportement attendu est donc de refuser la tâche ou de la rediriger vers une skill markdown-to-HTML orientée document.

En quoi md-review est-elle meilleure qu’un prompt classique ?

Un prompt classique peut produire un HTML attrayant, mais il risque souvent d’inventer des règles de mise en page, de manquer les conventions de numérotation des lignes ou de s’appuyer uniquement sur la couleur pour indiquer la sévérité. md-review utilise des scripts concrets de parsing et de rendu, une UX de revue à deux colonnes documentée et des contraintes d’accessibilité explicites. C’est un meilleur choix lorsque la cohérence et la sémantique de review sont importantes.

md-review est-elle accessible aux débutants ?

Elle est accessible aux débutants si vous connaissez déjà les blocs de code markdown et les unified diffs. Les débutants qui ne disposent que de commentaires en prose devront peut-être d’abord générer ou coller un vrai diff de PR. Le point de départ le plus simple consiste à exécuter les modes d’exemple dans les scripts, puis à adapter la structure markdown fournie à votre propre review.

Améliorer la skill md-review

Améliorer les entrées md-review avant le rendu

Le moyen le plus rapide d’améliorer la sortie md-review consiste à améliorer la review source. Incluez les chemins de fichiers dans les en-têtes unified diff standard, conservez les en-têtes de hunk @@ et gardez suffisamment de lignes de contexte pour que les reviewers comprennent le changement. Dans la mesure du possible, utilisez un finding par callout ; regrouper des problèmes sans lien dans une seule carte MAJOR rend la navigation de saut moins utile.

Éviter les modes d’échec fréquents

Les échecs courants incluent l’absence de --reviewer, des fenced diffs mal formés, des libellés de sévérité hors de la convention configurée et des annotations placées trop loin du diff auquel elles se rapportent. Un autre point plus subtil consiste à utiliser la sévérité comme un ton plutôt que comme une priorité. Une préférence de style formulée sèchement doit rester NIT ; un problème de justesse exprimé calmement peut être BLOCKER.

Itérer après la première sortie HTML

Après le premier rendu, vérifiez trois points : chaque finding apparaît-il dans la navigation de saut en haut de page, les annotations sont-elles rattachées aux hunks prévus, et les commentaires non ancrés sont-ils vraiment des commentaires généraux ? Si une annotation se retrouve au mauvais endroit, rapprochez-la du bloc diff pertinent au lieu d’essayer de corriger le HTML à la main.

Personnaliser sans casser le modèle de review

Utilisez la personnalisation pour refléter les conventions de l’équipe, pas pour affaiblir la structure. Une liste de sévérités personnalisée est pertinente si votre organisation utilise des libellés comme critical, important, suggestion et nit. Transformer la sortie en rapport narratif, masquer les icônes de sévérité ou retirer le pied de page du reviewer compromet ce que md-review est conçue pour garantir : une sortie de review responsable, accessible et centrée sur le diff.