valorisa Collaborative Technical Peer Review
Objectif
Cette skill guide une revue technique exigeante où plusieurs analyses sont confrontées, critiquées et consolidées afin de produire un résultat plus robuste que n'importe quelle contribution individuelle.
L'objectif n'est pas d'obtenir un consensus artificiel, mais d'améliorer progressivement la qualité technique, pédagogique et documentaire d'un travail.
Cas d'utilisation
Cette méthode est particulièrement adaptée à :
- cryptographie ;
- cybersécurité ;
- architecture logicielle ;
- documentation technique ;
- RFC et spécifications ;
- audits ;
- conception de bibliothèques ;
- documentation GitHub.
Principes
Les désaccords sont recherchés
Une divergence argumentée est une opportunité d'améliorer le document.
Toute critique doit être motivée
Une objection doit expliquer :
- pourquoi elle existe ;
- quelles hypothèses elle remet en cause ;
- quelles références ou raisonnements la soutiennent.
Les concessions sont explicites
Lorsqu'une critique est acceptée, la correction est documentée.
Lorsqu'elle est rejetée, la justification est également documentée.
La terminologie est normalisée
Les termes sont harmonisés avec les standards et la littérature du domaine lorsque cela est possible.
Déroulement
Étape 1
Analyser le document.
Identifier :
- erreurs ;
- ambiguïtés ;
- approximations ;
- raccourcis ;
- points solides.
Étape 2
Évaluer les différents niveaux de lecture.
Par exemple :
- vulgarisation ;
- ingénierie ;
- littérature académique.
Une affirmation peut être acceptable pour un niveau et insuffisante pour un autre.
Étape 3
Identifier les angles morts.
Chercher notamment :
- concepts absents ;
- hypothèses implicites ;
- contre-exemples ;
- incidents historiques ;
- limites des modèles.
Étape 4
Proposer des corrections.
Les corrections doivent :
- améliorer la précision ;
- préserver la lisibilité ;
- éviter le jargon inutile.
Étape 5
Consolider.
Produire une version révisée intégrant les corrections retenues.
Étape 6
Relire comme un reviewer externe.
Ne plus défendre le texte.
Chercher ce qui peut encore être amélioré.
Style attendu
- bienveillant ;
- factuel ;
- argumenté ;
- précis ;
- pédagogique ;
- transparent sur les incertitudes.
Éviter :
- l'argument d'autorité ;
- les jugements personnels ;
- le consensus forcé ;
- les formulations péremptoires.
Livrables
Selon le contexte :
- commentaire technique ;
- article ;
- README ;
- page de documentation ;
- ADR ;
- RFC ;
- guide pédagogique ;
- dépôt GitHub.
Critères de réussite
Une revue est réussie lorsque :
- les erreurs sont corrigées ;
- les ambiguïtés disparaissent ;
- les limites sont explicitées ;
- la pédagogie est améliorée ;
- la rigueur progresse sans sacrifier la compréhension ;
- le document final est plus robuste que chacune des versions intermédiaires.
Philosophie
Le désaccord n'est pas un échec de la revue.
C'est son moteur.
La qualité ne provient pas de l'absence de contradictions, mais de leur résolution argumentée.
L'objectif final n'est pas d'avoir raison, mais de produire un document durable, utile et techniquement fiable.