tag-duplicate-prs-issues

Tag des PR et Issues en Doublon

Utilisez cette compétence lorsqu'un mainteneur doit décider si une pull request ou une issue est un doublon de travail existant.

Cette compétence est destinée au tri et au regroupement par les mainteneurs. Elle ne sert pas à évaluer la qualité de l'implémentation d'une PR.

Configuration Requise

N'écrivez pas de groupes ou d'annotations de doublon tant que cette configuration n'est pas terminée. La découverte en lecture seule peut toujours avancer avec gitcrawl et gh en direct.

Compétences Compagnes

Utilisez d'abord $gitcrawl pour la découverte locale de candidats. Utilisez la compétence prtags du dépôt prtags à skills/prtags/SKILL.md lorsqu'elle est disponible.

Installer les CLI

Installez prtags à partir de la version épinglée ci-dessous. Ne comptez pas sur une ancienne version locale, sauf si le mainteneur souhaite explicitement tester un comportement non publié.

Chemin d'installation de prtags CLI :

GOBIN="$HOME/.local/bin" go install github.com/dutifuldev/prtags/cmd/[email protected]

prtags se trouve en dehors de l'organisation OpenClaw, donc cette installation reste épinglée à une version révisée que le proxy de module Go résout et que la base de données de somme de contrôle publique vérifie. GOBIN garde l'exécutable installé dans le même répertoire local utilisateur que l'installateur précédent, donc un PATH existant de $HOME/.local/bin continue à résoudre la version nouvellement installée. Ne l'installez pas en redirigeant un script distant dans un shell, et ne pointez pas l'installation vers une branche : l'une ou l'autre exécute ce que le tiers sert à l'exécution, avec les propres privilèges du mainteneur. Passer à une version plus récente de prtags est un changement révisé de ce fichier, pas une étape intermédiaire.

Authentifier prtags

prtags doit être connecté avec le propre compte GitHub du mainteneur via le flux OAuth de l'appareil. N'utilisez pas un token de mainteneur partagé pour un tri interactif.

prtags auth login
prtags auth status

Le résultat attendu est que prtags stocke l'identité du mainteneur connecté localement et utilise ce compte pour les écritures authentifiées.

Règle de Configuration Manquante

N'exigez pas de vérification préalable avant de démarrer le flux de travail. Procédez avec les étapes normales jusqu'à ce que vous ayez réellement besoin d'un outil ou d'un état de compte.

Dès que vous découvrez que prtags est manquant ou non connecté à l'étape d'écriture, arrêtez-vous immédiatement. Ne continuez pas en mode d'écriture partielle après ce point.

Si prtags est manquant, demandez à l'utilisateur d'exécuter la commande d'installation épinglée depuis Installer les CLI. Gardez cette section comme la seule source de la version installée ; n'improvisez pas d'autre chemin d'installation.

Si prtags auth status montre que l'utilisateur n'est pas connecté, demandez à l'utilisateur d'exécuter :

prtags auth login

Reprenez seulement après que l'outil manquant ou l'état de connexion a été corrigé.

Parcours de Lecture par Défaut

Pour la découverte de candidats dans ce flux de travail, utilisez d'abord gitcrawl. Considérez-le comme la couche d'historique local et de clustering pour les issues connexes, les tentatives de doublon et les fils fermés.

Utilisez gh ou gh api en direct pour le fil cible et pour tout candidat avant de porter un jugement actionnable. Utilisez GitHub en direct lorsque gitcrawl est manquant ou obsolète pour une raison concrète, telle que :

• la cible ou le candidat n'est pas encore présent
• les données locales sont clairement obsolètes ou incomplètes pour la décision que vous devez prendre
• gitcrawl génère une erreur, expire ou manque des données de voisinage/recherche nécessaires

Lorsque vous recourez à une recherche GitHub en direct, notez que vous l'avez fait et pourquoi.

Si une écriture ultérieure au niveau de la cible prtags échoue parce que son propre miroir n'a pas suivi, arrêtez-vous et signalez que le backend de curation manque l'objet cible au lieu de forcer une écriture de repli.

Objectif

Pour chaque PR ou issue cible :

1. rassembler les preuves de doublon
2. décider s'il s'agit d'un véritable doublon
3. créer ou réutiliser un groupe prtags pour ce cluster de doublons
4. enregistrer le jugement du mainteneur dans prtags
5. compter sur les écritures normales de groupe prtags pour déclencher la synchronisation des commentaires GitHub lorsque cette intégration est configurée

Rôles des Outils

Utilisez les outils avec ces limites :

• gitcrawl est la génération de candidats et le contexte historique
  • utilisez-le d'abord pour la recherche locale de titre/corps, les voisins, les clusters et la découverte de fils fermés
  • traitez chaque candidat comme une piste jusqu'à ce que GitHub en direct le confirme
• gh est la vérité en direct de GitHub
  • utilisez-le pour l'état cible, le corps, les commentaires, les revues, les fichiers, les issues liées et le statut actuel ouvert/fermé/fusionné
  • utilisez gh search seulement lorsque gitcrawl est obsolète, manque de données ou ne peut pas exprimer la requête nécessaire
• prtags est la couche de curation du mainteneur
  • utilisez-le pour créer ou réutiliser un groupe de doublons
  • utilisez-le pour enregistrer le statut de doublon, la confiance, la justification et le résumé du groupe
  • utilisez-le comme source de vérité pour le commentaire de groupe visible sur GitHub

Règles de Travail

• Ne qualifiez pas quelque chose de doublon uniquement parce que les titres sont similaires.
• Ne qualifiez pas quelque chose de doublon uniquement parce que les mêmes fichiers ont changé.
• Un cluster de doublons doit être basé sur le même problème visible par l'utilisateur, la même intention et un contexte d'implémentation ou d'investigation sensiblement chevauchant.

Règle du Groupe Unique

Traitez les groupes de doublons comme exclusifs. Une PR ou une issue ne doit appartenir qu'à un seul groupe de doublons à la fois.

Cela signifie :

• avant de créer un nouveau groupe, recherchez un groupe existant qui représente déjà la même histoire de doublon
• si la cible semble déjà appartenir à un groupe de doublons différent, arrêtez-vous et résolvez d'abord ce conflit
• ne créez pas un deuxième groupe pour la même cible simplement parce que le libellé est légèrement différent
• si deux groupes existants plausibles se chevauchent et que vous ne pouvez pas fusionner le jugement en toute sécurité, arrêtez-vous et demandez au mainteneur

Cette règle est plus importante que la rapidité. La compétence doit maintenir un cluster de doublons cohérent par problème, et non plusieurs clusters presque identiques.

Ce que Représente un Bon Groupe de Doublons

Un groupe de doublons doit décrire le problème sous-jacent et la direction de correction prévue. Ne regroupez pas les éléments uniquement parce qu'ils partagent un mot-clé.

Bonne forme de groupe :

• même bogue visible par l'utilisateur ou même tâche visible par le mainteneur
• même sous-système ou surface de code
• même direction de changement prévue
• même chemin de résolution de doublon probable

Mauvaise forme de groupe :

• "toutes les PR qui touchent à Slack"
• "toutes les issues mentionnant la réessai"
• "tous les éléments liés à l'authentification"

Le titre du groupe doit nommer le vrai problème. La description du groupe doit résumer l'intention et la surface de code.

Exemples :

• gateway : régression de démarrage due au bootstrap de statut de canal
• whatsapp : gestion du délai d'attente de la pré-vérification QR
• release : lacunes de validation entre systèmes d'exploitation

Liste de Vérification des Preuves

Avant de déclarer un doublon, rassemblez des preuves d'au moins deux catégories. Les voisins de gitcrawl, les résultats de recherche et l'appartenance à un cluster comptent comme génération de candidats, pas comme preuve suffisante en eux-mêmes.

Pour les PR :

• même énoncé de problème ou presque identique
• mêmes fichiers modifiés ou plages de fichiers chevauchantes
• même direction de correction
• même sous-système et mode de défaillance
• même issue liée ou même symptôme visible par l'utilisateur

Pour les issues :

• même problème visible par l'utilisateur
• même histoire de reproduction ou même mode de défaillance
• même zone de correction probable
• mêmes PR déjà liées ou discutées
• mêmes mainteneurs déjà orientés vers le même regroupement de doublon

Si vous n'avez qu'une similarité de formulation, ce n'est pas suffisant.

Étape 1 : Lire la Cible

Commencez par lire la cible elle-même. Utilisez GitHub en direct pour l'état actuel de la cible.

Pour une PR :

gh pr view <number> --json number,title,state,mergedAt,body,closingIssuesReferences,files,comments,reviews,statusCheckRollup

Pour une issue :

gh issue view <number> --json number,title,state,body,comments,closedAt

Enregistrez :

• type et numéro de la cible
• titre
• énoncé du problème
• intention proposée
• sous-système
• si elle est ouverte, fermée ou fusionnée
• s'il existe déjà un fil de doublon probable mentionné par des humains

Étape 2 : Rechercher largement avec Gitcrawl

Utilisez d'abord gitcrawl car c'est la source d'historique locale et de clustering d'OpenClaw. Ne passez pas à une recherche large en direct sur GitHub sauf si gitcrawl manque de données, est obsolète ou échoue.

Commencez par la cible et les fils voisins :

gitcrawl threads openclaw/openclaw --numbers <issue-or-pr-number> --include-closed --json
gitcrawl neighbors openclaw/openclaw --number <issue-or-pr-number> --limit 20 --json

Puis recherchez des phrases clés et des termes de sous-système :

gitcrawl search openclaw/openclaw --query "<key phrase from title or body>" --mode hybrid --limit 20 --json
gitcrawl search openclaw/openclaw --query "<subsystem or error phrase>" --mode hybrid --limit 20 --json

Inspectez les clusters probables :

gitcrawl cluster-detail openclaw/openclaw --id <cluster-id> --member-limit 20 --body-chars 280 --json

Pour les PR, vérifiez le chevauchement probable de code avec les données de fichiers en direct :

gh pr view <candidate-pr> --json number,title,state,mergedAt,files,body,comments,reviews

Pour les issues, vérifiez l'état de l'issue en doublon probable et les commentaires en direct :

gh issue view <candidate-issue> --json number,title,state,body,comments,closedAt

Étape 3 : Utiliser la Recherche GitHub en Direct pour les Lacunes

Utilisez la recherche ciblée en direct sur GitHub après gitcrawl lorsque :

• la cible est trop récente pour le magasin local
• les commentaires ou revues sont importants et le magasin local en manque
• la phrase exacte n'est pas apparue dans les résultats locaux mais l'issue/PR est assez récente pour que GitHub devrait la connaître

gh search prs --repo openclaw/openclaw --match title,body --limit 50 -- "<key phrase>"
gh search issues --repo openclaw/openclaw --match title,body --limit 50 -- "<key phrase>"
gh search issues --repo openclaw/openclaw --match comments --limit 50 -- "<error or maintainer phrase>"

Étape 4 : Décider du Résultat

Choisissez l'un de ces résultats :

• not_duplicate
• duplicate_needs_judgment
• duplicate_confirmed

Utilisez duplicate_confirmed seulement lorsque les preuves sont assez solides pour que le mainteneur puisse fermer ou re-tagger l'élément en doublon en toute sécurité.

Utilisez duplicate_needs_judgment lorsque :

• le problème semble identique mais l'objectif d'implémentation diffère
• le chevauchement de code est faible
• le libellé de l'issue est ambigu
• il peut y avoir deux interprétations valides de groupe de doublons
• la cible semble intersecter deux groupes de doublons existants

Étape 5 : Réutiliser ou Créer un Groupe prtags

Avant de créer un groupe, recherchez un groupe existant dans prtags.

Commencez par une recherche textuelle parmi les groupes :

prtags search text -R openclaw/openclaw "<problem phrase>" --types group --limit 10
prtags search similar -R openclaw/openclaw "<problem summary>" --types group --limit 10
prtags group list -R openclaw/openclaw

Inspectez les groupes probables :

prtags group get <group-id>
prtags group get <group-id> --include-metadata

Réutilisez un groupe existant lorsque :

• il représente le même problème
• il contient déjà des membres clairement liés
• l'ajout de la cible maintiendrait la cohérence du groupe

N'élargissez pas un groupe existant simplement parce que gitcrawl a placé plusieurs PR ou issues proches les unes des autres. Confirmez que le chemin d'implémentation réel et l'intention du mainteneur correspondent toujours avant d'ajouter le nouveau membre.

Créez un nouveau groupe seulement lorsqu'aucun groupe existant ne correspond clairement.

Créez le groupe avec un titre basé sur le problème et une description basée sur l'intention :

prtags group create -R openclaw/openclaw \
  --kind mixed \
  --title "<problem-centered title>" \
  --description "<same intent, subsystem, and duplicate-resolution path>" \
  --status open

Puis attachez la cible et les membres en doublon connus :

prtags group add-pr <group-id> <pr-number>
prtags group add-issue <group-id> <issue-number>

Si une cible semble déjà appartenir à un autre groupe de doublons et que vous ne pouvez pas réutiliser ce groupe en toute sécurité, arrêtez-vous. Ne créez pas un deuxième groupe.

Étape 6 : Assurer l'Existence des Champs d'Annotation

Utilisez field ensure pour que la compétence soit idempotente.

Champs recommandés au niveau de la cible :

prtags field ensure -R openclaw/openclaw --name duplicate_status --scope pull_request --type enum --enum-values not_duplicate,candidate,confirmed --filterable
prtags field ensure -R openclaw/openclaw --name duplicate_status --scope issue --type enum --enum-values not_duplicate,candidate,confirmed --filterable
prtags field ensure -R openclaw/openclaw --name duplicate_confidence --scope pull_request --type enum --enum-values low,medium,high --filterable
prtags field ensure -R openclaw/openclaw --name duplicate_confidence --scope issue --type enum --enum-values low,medium,high --filterable
prtags field ensure -R openclaw/openclaw --name duplicate_rationale --scope pull_request --type text --searchable
prtags field ensure -R openclaw/openclaw --name duplicate_rationale --scope issue --type text --searchable

Champs recommandés au niveau du groupe :

prtags field ensure -R openclaw/openclaw --name duplicate_confidence --scope group --type enum --enum-values low,medium,high --filterable
prtags field ensure -R openclaw/openclaw --name duplicate_rationale --scope group --type text --searchable
prtags field ensure -R openclaw/openclaw --name cluster_summary --scope group --type text --searchable

Étape 7 : Enregistrer le Jugement du Mainteneur dans prtags

Pour une PR :

prtags annotation pr set -R openclaw/openclaw <pr-number> \
  duplicate_status=confirmed \
  duplicate_confidence=high \
  duplicate_rationale="<same problem, same fix direction, overlapping files and comments>"

Pour une issue :

prtags annotation issue set -R openclaw/openclaw <issue-number> \
  duplicate_status=confirmed \
  duplicate_confidence=high \
  duplicate_rationale="<same user-visible problem and same intended fix path>"

Pour le groupe :

prtags annotation group set <group-id> \
  duplicate_confidence=high \
  cluster_summary="<one-sentence problem summary>" \
  duplicate_rationale="<why these items belong in one duplicate cluster>"

Lorsque les preuves sont incomplètes, définissez duplicate_status=candidate et réduisez la confiance.

Si une écriture d'annotation par PR ou par issue échoue parce que prtags ne peut pas résoudre la cible, ne forcez pas un chemin d'écriture de repli. Conservez l'état de groupe que vous avez pu écrire, signalez que le backend de curation manque toujours l'objet cible, et reportez l'écriture de l'annotation à plus tard.

Étape 8 : Générer un Résumé

Après avoir enregistré le groupe et les annotations, générez un résumé du résultat. N'incluez que ce qui est pertinent pour le contexte du mainteneur.

Le résumé doit inclure :

• l'identification de la cible et l'état de doublon
• les preuves clés (pas tous les résultats bruts, juste les pièces qui appuient la décision)
• le groupe créé ou réutilisé avec son identifiant
• la confiance dans la décision
• tout problème non résolu ou tout travail en attente

Étape 9 : Signaler l'Incohérence

Avant de terminer, vérifiez si le nouveau groupe ou membre semble entrer en conflit avec une connaissance plus large du dépôt. Faites correspondre le titre et la description du groupe avec les conventions de sous-système et de terminologie des issues/PR observées.

Si vous découvrez que la cible ou le groupe correspond à une convention de dénomination qui n'est pas utilisée ailleurs (par exemple, un nom de sous-système que vous avez inventé mais que le dépôt n'utilise pas), signalez-le comme un risque d'incohérence avant de finaliser.

Ne vous arrêtez pas pour cela ; les mainteneurs peuvent vous guider plus tard, mais le résumé doit noter que la terminologie que vous avez utilisée peut ne pas correspondre à la convention établie.

Arrêt : Doublon Ne Peut Pas Être Résolu de Manière Fiable

Arrêtez-vous et signalez l'état lorsque :

• la cible semble intersecter deux groupes de doublons existants et vous ne pouvez pas décider lequel est correct
• la cible semble être un doublon d'un élément qui a déjà été fermé comme en double, mais les preuves sont contradictoires
• la preuve minimum de deux catégories n'est pas atteignable avec les données disponibles
• les mainteneurs humains ont déjà commenté des opinions conflictuelles sur le doublon

L'arrêt signifie : documentez ce que vous avez trouvé, dites ce que vous ne pouvez pas décider, et laissez la décision finale au mainteneur. Ne créez pas de groupe dans ce cas.