requesting-code-review

Présentation de la skill requesting-code-review

La skill requesting-code-review propose un workflow léger pour déclencher une revue de code ciblée au bon moment, sur le bon diff, avec suffisamment de contexte d’implémentation pour qu’un agent reviewer puisse fournir un retour utile. Au lieu d’un vague « merci de relire mon code », elle vous pousse à transmettre une plage de commits, un résumé des changements et les exigences visées.

Ce que fait réellement la skill requesting-code-review

Au fond, requesting-code-review vous indique de lancer le sous-agent superpowers:code-reviewer à l’aide du template préparé dans code-reviewer.md. Sa vraie différence ne vient pas d’une automatisation sophistiquée, mais du cadrage de la revue. Le reviewer voit le livrable et le plan, pas tout l’historique de votre session, ce qui resserre le périmètre et rend les retours plus faciles à exploiter.

À qui convient l’installation de requesting-code-review

Cette skill est particulièrement adaptée aux développeurs et aux utilisateurs d’agents IA qui :

• travaillent avec des workflows basés sur des commits
• livrent des fonctionnalités par étapes
• veulent un point de contrôle reproductible de type « review avant de continuer »
• utilisent des sous-agents et ont besoin d’un handoff plus propre qu’un prompt générique

Elle est particulièrement utile si vous avez tendance à demander une review trop tard, une fois que plusieurs tâches se sont accumulées dans un diff trop volumineux.

Le vrai besoin auquel elle répond

On n’installe pas requesting-code-review simplement pour « obtenir une review ». On l’installe pour réduire les retouches évitables :

• détecter les problèmes avant le merge
• valider l’implémentation par rapport au plan initial
• obtenir un feedback classé par niveau de sévérité
• préserver le contexte de la tâche principale pendant qu’un agent reviewer inspecte le code séparément

Pourquoi cette skill est plus utile qu’un simple prompt de review

La requesting-code-review skill apporte une structure concrète qui manque souvent aux prompts improvisés :

• des recommandations de timing pour la review : après chaque tâche, après une grosse fonctionnalité, avant le merge
• des entrées BASE_SHA et HEAD_SHA explicites
• un template de review couvrant la qualité du code, l’architecture, les tests, les exigences et l’aptitude à la production
• des catégories de sévérité qui facilitent le traitement des suites à donner

Le résultat est donc bien plus actionnable qu’un simple « regarde mes derniers changements ».

Ce qu’il faut vérifier en priorité avant de l’adopter

La principale question d’adoption est celle du bon fit : cette skill fonctionne surtout si votre travail est représenté par une plage git propre et si vous pouvez décrire brièvement le comportement attendu. Si votre branche est désordonnée, si votre plan est flou ou si vos changements mélangent des modifications sans rapport, la qualité de la review baissera.

Limite importante à connaître dès le départ

requesting-code-review for Code Review n’est pas à lui seul un système complet de revue de code. Il n’embarque ni scripts, ni règles d’application, ni vérifications spécifiques à votre dépôt. C’est avant tout un pattern discipliné de prompting et de handoff. C’est précieux, mais il faut s’attendre à ce que la qualité dépende fortement de la plage de commits choisie et de la clarté de vos exigences.

Comment utiliser la skill requesting-code-review

Installer requesting-code-review dans votre configuration de skills

Si vous utilisez le pattern Skills CLI utilisé dans l’ensemble du dépôt, installez-la avec :

npx skills add https://github.com/obra/superpowers --skill requesting-code-review

Si votre environnement expose déjà la collection obra/superpowers, il suffit d’activer ou de référencer la skill requesting-code-review depuis ce pack.

Commencez par lire ces fichiers

Pour une évaluation rapide, commencez par :

1. skills/requesting-code-review/SKILL.md
2. skills/requesting-code-review/code-reviewer.md

SKILL.md explique à quel moment déclencher une review. code-reviewer.md est le fichier le plus important si la qualité de sortie vous importe, car il montre précisément ce que le reviewer doit évaluer.

Comprendre les moments de déclenchement prévus

La skill est conçue pour être utilisée :

• après chaque tâche dans un développement piloté par sous-agents
• après une fonctionnalité majeure
• avant le merge vers main

Parmi les moments optionnels mais très utiles :

• quand vous bloquez et voulez un regard neuf
• avant un refactor risqué
• après la correction d’un bug complexe

Si vous ne l’utilisez qu’à la toute fin d’une grosse branche, vous perdez une grande partie de son intérêt.

Rassembler le minimum d’informations avant de l’appeler

La skill fonctionne mieux si vous fournissez :

• ce qui a été implémenté
• le plan ou les exigences
• BASE_SHA
• HEAD_SHA
• une brève description du changement

Commandes git typiques :

BASE_SHA=$(git rev-parse HEAD~1)
HEAD_SHA=$(git rev-parse HEAD)

Sur une feature branch, origin/main peut être une meilleure base que HEAD~1 si vous voulez une fenêtre de review plus large.

Utiliser une plage de diff propre, pas une demande floue du type « mes derniers changements »

C’est la partie à plus fort levier du pattern d’usage requesting-code-review. Une review attachée à BASE_SHA..HEAD_SHA est nettement meilleure que de demander à un agent de deviner ce qui a changé à partir du working tree ou de l’historique de chat.

Bien :

• « Review commits from feature start to current head against the signup flow requirements. »

Faible :

• « Can you review my recent auth changes? »

La version solide réduit le périmètre et limite les suppositions côté reviewer.

Transformer un objectif vague en vraie demande de review

Une demande approximative comme celle-ci est trop légère :

Please review my new feature.

Une demande plus solide, alignée sur la skill, ressemble à ceci :

Review the password reset implementation for production readiness.

What was implemented:
- Added reset token generation and validation
- Added reset email endpoint
- Added UI flow for requesting and completing reset

Plan/requirements:
- Tokens expire after 30 minutes
- Single-use tokens only
- No user enumeration from the request endpoint
- Existing login flow must remain unchanged

Base SHA: abc1234
Head SHA: def5678
Description:
Task 2 of auth hardening. Main changes are in API handlers, email service, and reset form.

Cela donne au reviewer assez de contexte pour juger la justesse de l’implémentation, et pas seulement le style.

Lancer le sous-agent reviewer comme la skill l’attend

Les indications du dépôt recommandent d’utiliser l’outil Task avec le type superpowers:code-reviewer, puis de remplir le template dans code-reviewer.md. Ce template demande au reviewer de :

• comparer l’implémentation au plan
• inspecter le git diff
• vérifier la qualité, l’architecture, les tests et la readiness pour la production
• renvoyer ses constats par niveau de sévérité

Si votre plateforme d’agents prend en charge les sous-agents, gardez la review isolée au lieu de la mélanger à la conversation de travail principale.

Ce que le template reviewer détecte le mieux

La checklist intégrée est particulièrement efficace pour faire ressortir :

• les exigences manquantes
• les lacunes évidentes de readiness production
• les problèmes de couverture de tests
• les préoccupations d’architecture
• les edge cases dangereux
• les oublis liés à la rétrocompatibilité ou aux migrations

En revanche, elle est moins spécialisée pour la conformité métier, les conventions propres au dépôt ou la vérification approfondie à l’exécution, sauf si vous les ajoutez explicitement.

Workflow conseillé pour des projets réels

Un requesting-code-review guide pragmatique ressemble à ceci :

1. terminer une tâche bien délimitée
2. identifier la plage de diff exacte
3. résumer l’intention et les critères d’acceptation
4. lancer le reviewer avec le template
5. corriger les problèmes critiques et importants
6. relancer une review si les corrections sont substantielles
7. poursuivre le développement ou merger

Cette skill est la plus efficace comme point de contrôle entre des étapes d’implémentation, et pas seulement comme dernier garde-fou.

Conseils qui améliorent réellement la qualité du résultat

Pour obtenir une meilleure review :

• utilisez une plage de diff qui contient un seul changement logique
• incluez des critères d’acceptation, pas seulement un nom de fonctionnalité
• signalez les zones à risque comme les migrations, l’auth, la concurrence, le caching ou les contrats d’API
• précisez si des tests ont été ajoutés et de quel type
• indiquez si des breaking changes sont attendus ou interdits

Ces éléments aident le reviewer à distinguer les arbitrages intentionnels des omissions accidentelles.

Les mauvais usages les plus fréquents

La décision d’installer requesting-code-review a moins de sens si votre équipe :

• regroupe régulièrement de nombreux changements sans rapport dans une même plage
• ne formalise pas les exigences
• n’utilise pas de bornes git réellement significatives
• attend de la skill qu’elle remplace la validation humaine ou la CI

Dans ces cas-là, mieux vaut d’abord assainir le workflow, sinon les reviews seront plus bruyantes.

FAQ sur la skill requesting-code-review

requesting-code-review est-elle adaptée aux débutants ?

Oui, si vous maîtrisez déjà les bases de git comme les commits et les SHA. La skill est simple, mais elle suppose que vous sachiez définir ce qui a changé et ce que cela devait faire. Les débutants qui sautent ce contexte obtiendront quand même du feedback, mais il sera moins fiable.

Cette skill review-t-elle les changements non commités ?

Pas par conception. Le workflow repose sur BASE_SHA et HEAD_SHA, donc il est plus solide sur du travail commité. Vous pouvez l’adapter à des changements unstaged ou non commités, mais vous vous éloignez alors de la structure centrale de la skill, et la review devient en général moins reproductible.

En quoi requesting-code-review diffère-t-elle d’une simple demande à une IA de relire mon code ?

Un prompt classique produit souvent une review générique, car le modèle doit deviner le périmètre, l’intention et les critères d’acceptation. requesting-code-review améliore cela en imposant :

• un diff explicite
• un résumé clair de l’implémentation
• le plan ou les exigences d’origine
• un format de sortie basé sur la sévérité

Le résultat est généralement plus facile à croire et surtout plus facile à exploiter.

Quand ne faut-il pas utiliser requesting-code-review ?

Évitez-la quand :

• votre changement est trop incomplet pour être évalué
• le diff mélange plusieurs fonctionnalités sans rapport
• vous ne connaissez pas encore le comportement attendu
• vous avez surtout besoin de checks statiques spécifiques au dépôt, plus que d’une review fondée sur le jugement

Elle est aussi peu adaptée si votre équipe ne travaille jamais à partir de plages de commits git.

Remplace-t-elle la revue de code humaine ?

Non. Son meilleur usage est celui d’une pré-review ou d’un contrôle qualité entre deux étapes. Elle peut détecter des problèmes tôt et fluidifier la review humaine ensuite, mais elle ne remplace ni l’expertise métier, ni les conventions d’équipe, ni les exigences de validation de l’organisation.

requesting-code-review est-elle réservée aux grosses fonctionnalités ?

Non. En réalité, c’est sur les petits diffs qu’elle est la plus utile. La skill encourage explicitement des reviews précoces et fréquentes, souvent bien plus efficaces qu’une unique grosse passe finale.

Quel niveau d’intégration avec l’écosystème faut-il attendre ?

Cette skill s’intègre le mieux dans le workflow obra/superpowers, surtout si vous utilisez déjà des sous-agents. Elle est plus légère qu’un framework complet de review et plus simple à adopter qu’une automatisation de review sur mesure, mais cela signifie aussi moins de garde-fous.

Comment améliorer la skill requesting-code-review

Donnez au reviewer de meilleures exigences, pas seulement un meilleur code

Le mode d’échec le plus fréquent vient d’un contexte de plan trop faible. Si vous dites seulement « implemented notifications », le reviewer ne peut pas savoir si l’absence de mécanisme de retry est un bug ou hors périmètre. Ajoutez des attentes concrètes :

• conditions de déclenchement
• comportement en cas d’erreur
• attentes de rétrocompatibilité
• exigences de performance ou de sécurité

De meilleures exigences produisent de meilleurs jugements de review.

Utiliser la plus petite unité de review réellement pertinente

La requesting-code-review skill donne ses meilleurs résultats sur une tâche unique ou un ensemble de changements étroitement liés. Si le diff comprend du schéma, des changements d’API, des mises à jour UI et du nettoyage sans rapport, les constats deviennent plus larges et moins actionnables. Scindez le travail en unités reviewables dès que possible.

Choisir le bon commit de base

Un mauvais BASE_SHA produit des retours trompeurs. Si vous utilisez HEAD~1 alors que la fonctionnalité s’étale sur six commits, le reviewer ne voit pas assez. Si vous partez d’une base trop ancienne, il voit trop de bruit. Choisissez la base qui correspond à l’unité logique de travail que vous voulez faire évaluer.

Remplacer les placeholders par des éléments précis que le reviewer peut tester mentalement

Le template fourni utilise des placeholders comme :

• {WHAT_WAS_IMPLEMENTED}
• {PLAN_OR_REQUIREMENTS}
• {BASE_SHA}
• {HEAD_SHA}
• {DESCRIPTION}

Ne les remplissez pas avec des résumés d’une ligne si le changement comporte des risques. Décrivez le comportement attendu de façon concrète. Par exemple, « prevents user enumeration and invalidates token after first successful reset » est bien plus solide que « added password reset ».

Indiquer au reviewer où se situe le risque

Si vous connaissez les surfaces à risque, dites-le :

• « Please pay special attention to race conditions around token reuse. »
• « Check backward compatibility for existing API consumers. »
• « Focus on whether tests cover the error path and expiry boundary. »

Cela resserre l’attention et augmente les chances d’obtenir des constats utiles.

Renforcer la review après le premier passage

Après le premier résultat :

1. corrigez les problèmes critiques manifestement valides
2. contestez les constats qui vous semblent erronés
3. clarifiez les exigences manquantes
4. relancez une seconde review sur le diff mis à jour si les changements sont substantiels

La skill elle-même encourage la contradiction quand le reviewer se trompe. C’est bon signe : elle est conçue pour soutenir le jugement, pas pour le remplacer.

Ajouter des critères de review propres au dépôt quand c’est nécessaire

Le code-reviewer.md standard couvre bien les dimensions communes de la review, mais beaucoup d’équipes ont besoin de plus. Améliorez requesting-code-review for Code Review en ajoutant des checks spécifiques au projet, par exemple :

• règles de déploiement des migrations
• exigences d’observabilité
• attentes en matière d’accessibilité
• points de contrôle sécurité
• conventions de langage ou de framework

C’est l’amélioration la plus importante si vous voulez des sorties moins génériques.

Surveiller ces modes d’échec récurrents

Les baisses de qualité viennent généralement de :

• exigences absentes ou vagues
• plages de commits trop bruyantes
• absence d’indications sur le comportement non fonctionnel attendu
• demande de review après accumulation d’un trop grand nombre de tâches
• traitement de suggestions mineures comme obligatoires tout en manquant des problèmes critiques de conception

Si la sortie vous paraît superficielle, vérifiez d’abord les entrées.

Améliorer la sortie en demandant des décisions, pas seulement des défauts

Un pattern d’usage requesting-code-review usage plus solide consiste à demander au reviewer d’évaluer aussi les arbitrages. Par exemple :

• « Flag any unnecessary complexity. »
• « Call out if this should be split before merge. »
• « Assess whether current tests justify production readiness. »

Vous poussez ainsi la review au-delà de commentaires de type lint pour aller vers une vraie évaluation de qualité de release.

Manière concrète de faire évoluer la skill dans votre propre setup

Si vous adoptez sérieusement cette skill, personnalisez d’abord trois éléments :

1. votre règle préférée pour choisir le commit de base
2. un format standard pour les exigences et les critères d’acceptation
3. des éléments de checklist supplémentaires pour votre stack et votre processus de release

Ces ajouts conservent la simplicité de requesting-code-review tout en la rendant nettement plus utile au quotidien.