etiquetar-prs-issues-duplicados

Etiquetar PRs e Issues Duplicados

Usa esta habilidad cuando un mantenedor necesite decidir si un pull request o issue es un duplicado de trabajo existente.

Esta habilidad es para la clasificación y agrupación por parte del mantenedor. No es para revisar la calidad de implementación de un PR.

Configuración Requerida

No escribas grupos o anotaciones duplicados hasta que esta configuración esté completa. El descubrimiento de solo lectura aún puede proceder con gitcrawl y gh en vivo.

Habilidades Complementarias

Usa $gitcrawl primero para el descubrimiento local de candidatos. Usa la habilidad prtags del repositorio prtags en skills/prtags/SKILL.md cuando esté disponible.

Instalar las CLI

Instala prtags desde la versión anclada a continuación. No dependas de una compilación local antigua a menos que el mantenedor quiera explícitamente probar comportamiento no publicado.

Ruta de instalación de la CLI prtags:

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

prtags vive fuera de la organización OpenClaw, por lo que esta instalación permanece anclada a una versión revisada que el proxy de módulos Go resuelve y la base de datos de suma de verificación pública verifica. GOBIN mantiene ejecutable instalado en el mismo directorio local de usuario que el instalador anterior, por lo que un PATH existente con $HOME/.local/bin sigue resolviendo la versión recién instalada. No lo instales canalizando un script remoto a un shell, y no apuntes la instalación a una rama: cualquiera de los dos ejecuta lo que el tercero sirva en tiempo de ejecución, con los propios privilegios del mantenedor. Pasar a una versión más nueva de prtags es un cambio revisado a este archivo, no un paso intermedio de la tarea.

Autenticar prtags

prtags debe iniciar sesión con la cuenta de GitHub del mantenedor a través del flujo de dispositivo OAuth. No uses un token de mantenedor compartido para la clasificación interactiva.

prtags auth login
prtags auth status

El resultado esperado es que prtags almacene la identidad del mantenedor conectado localmente y use esa cuenta para escrituras autenticadas.

Regla de Falta de Configuración

No requieras una verificación previa antes de comenzar el flujo de trabajo. Procede con los pasos normales hasta que realmente necesites una herramienta o estado de cuenta.

Tan pronto como descubras que prtags falta o no ha iniciado sesión en el paso de escritura, detente inmediatamente. No continúes en un modo de escritura parcial después de ese punto.

Si prtags falta, pide al usuario que ejecute el comando de instalación anclado desde Instalar las CLI. Mantén esa sección como la única fuente de la versión instalada; no improvises otra ruta de instalación.

Si prtags auth status muestra que el usuario no ha iniciado sesión, pídele que ejecute:

prtags auth login

Reanuda solo después de que la herramienta faltante o el estado de inicio de sesión se hayan solucionado.

Predeterminado de Ruta de Lectura

Para el descubrimiento de candidatos en este flujo de trabajo, usa gitcrawl primero. Trátalo como la capa de historial local y agrupación para hilos relacionados, intentos duplicados y discusiones cerradas.

Usa gh en vivo o gh api para el hilo objetivo y para cualquier candidato antes de hacer un juicio procesable. Usa GitHub en vivo cuando gitcrawl falte o esté desactualizado por una razón concreta, como:

• el objetivo o candidato aún no está presente
• los datos locales están claramente desactualizados o incompletos para la decisión que necesitas tomar
• gitcrawl da errores, se agota el tiempo de espera o carece de los datos de vecinos/búsqueda necesarios

Cuando recurras a la búsqueda en GitHub en vivo, anota que lo hiciste y por qué.

Si una escritura posterior a nivel de objetivo de prtags falla porque su propio espejo no se ha puesto al día, detente y reporta que el backend de curación no tiene el objeto objetivo en lugar de forzar una ruta de escritura alternativa.

Objetivo

Para cada PR o issue objetivo:

1. recopilar evidencia de duplicado
2. decidir si es un duplicado real
3. crear o reutilizar un grupo de prtags para ese clúster de duplicados
4. guardar el juicio del mantenedor en prtags
5. confiar en las escrituras normales de grupos de prtags para impulsar la sincronización de comentarios de GitHub cuando esa integración esté configurada

Roles de las Herramientas

Usa las herramientas con estos límites:

• gitcrawl es generación de candidatos y contexto histórico
  • úsalo primero para búsqueda local de título/cuerpo, vecinos, clústeres y descubrimiento de hilos cerrados
  • trata cada candidato como una pista hasta que GitHub en vivo lo confirme
• gh es la verdad en vivo de GitHub
  • úsalo para el estado del objetivo, cuerpo, comentarios, revisiones, archivos, issues vinculados y estado actual abierto/cerrado/fusionado
  • usa gh search solo cuando gitcrawl esté desactualizado, falten datos o no pueda expresar la consulta necesaria
• prtags es la capa de curación del mantenedor
  • úsalo para crear o reutilizar un grupo de duplicados
  • úsalo para guardar el estado de duplicado, confianza, justificación y resumen del grupo
  • úsalo como fuente de verdad para el comentario del grupo visible en GitHub

Reglas de Trabajo

• No llames duplicado a algo solo porque los títulos son similares.
• No llames duplicado a algo solo porque cambiaron los mismos archivos.
• Un clúster de duplicados debe basarse en el mismo problema visible para el usuario, la misma intención y un contexto de implementación o investigación sustancialmente superpuesto.

Regla de un Grupo

Trata los grupos de duplicados como exclusivos. Un PR o issue debe pertenecer como máximo a un grupo de duplicados a la vez.

Eso significa:

• antes de crear un nuevo grupo, busca un grupo existente que ya represente la misma historia de duplicado
• si el objetivo ya parece pertenecer a un grupo de duplicados diferente, detente y resuelve ese conflicto primero
• no crees un segundo grupo para el mismo objetivo solo porque la redacción es ligeramente diferente
• si dos grupos existentes plausibles se superponen y no puedes fusionar el juicio de manera segura, detente y pregunta al mantenedor

Esta regla importa más que la velocidad. La habilidad debe mantener un clúster de duplicados coherente por problema, no muchos clústeres casi duplicados.

Qué Representa un Buen Grupo de Duplicados

Un grupo de duplicados debe describir el problema subyacente y la dirección de corrección prevista. No agrupes elementos solo porque comparten una palabra clave.

Buena forma de grupo:

• mismo error visible para el usuario o misma tarea visible para el mantenedor
• mismo subsistema o superficie de código
• misma dirección de cambio prevista
• misma ruta de resolución de duplicado probable

Mala forma de grupo:

• "todos los PRs que tocan Slack"
• "todos los issues que mencionan reintento"
• "todos los elementos relacionados con autenticación"

El título del grupo debe nombrar el problema real. La descripción del grupo debe resumir la intención y la superficie de código.

Ejemplos:

• gateway: regresión de inicio desde el arranque del estado del canal
• whatsapp: manejo del tiempo de espera de verificación previa de QR
• release: brechas de validación entre sistemas operativos

Lista de Verificación de Evidencia

Antes de declarar un duplicado, recopila evidencia de al menos dos categorías. Los vecinos de gitcrawl, los resultados de búsqueda y la membresía en clústeres cuentan como generación de candidatos, no como prueba suficiente por sí mismos.

Para PRs:

• misma declaración de problema o casi la misma
• mismos archivos cambiados o rangos de archivos superpuestos
• misma dirección de corrección
• mismo subsistema y modo de fallo
• mismo issue vinculado o mismo síntoma visible para el usuario

Para issues:

• mismo problema visible para el usuario
• misma historia de reproducción o mismo modo de fallo
• misma área de corrección probable
• mismos PRs ya vinculados o discutidos
• mismos mantenedores ya dirigiendo hacia la misma agrupación de duplicados

Si solo tienes similitud de redacción, eso no es suficiente.

Paso 1: Leer el Objetivo

Comienza leyendo el objetivo en sí. Usa GitHub en vivo para el estado actual del objetivo.

Para un PR:

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

Para un issue:

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

Registra:

• tipo y número del objetivo
• título
• declaración del problema
• intención propuesta
• subsistema
• si está abierto, cerrado o fusionado
• si ya hay un hilo duplicado probable mencionado por humanos

Paso 2: Buscar Ampliamente con Gitcrawl

Usa gitcrawl primero porque es la fuente local de historial y agrupación de OpenClaw. No cambies a la búsqueda amplia en GitHub en vivo a menos que gitcrawl falte datos, esté desactualizado o falle.

Comienza con el objetivo y los hilos cercanos:

gitcrawl threads openclaw/openclaw --numbers <número-de-issue-o-pr> --include-closed --json
gitcrawl neighbors openclaw/openclaw --number <número-de-issue-o-pr> --limit 20 --json

Luego busca frases clave y términos del subsistema:

gitcrawl search openclaw/openclaw --query "<frase clave del título o cuerpo>" --mode hybrid --limit 20 --json
gitcrawl search openclaw/openclaw --query "<subsistema o frase de error>" --mode hybrid --limit 20 --json

Inspecciona clústeres probables:

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

Para PRs, verifica la probable superposición de código con datos de archivos en vivo:

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

Para issues, verifica el estado del issue duplicado probable y los comentarios en vivo:

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

Paso 3: Usar Búsqueda en GitHub en Vivo para Brechas

Usa la búsqueda dirigida en GitHub en vivo después de gitcrawl cuando:

• el objetivo es demasiado reciente para el almacén local
• los comentarios o revisiones son importantes y el almacén local carece de ellos
• la frase exacta no apareció en los resultados locales pero el issue/PR es lo suficientemente reciente como para que GitHub debería conocerlo

gh search prs --repo openclaw/openclaw --match title,body --limit 50 -- "<frase clave>"
gh search issues --repo openclaw/openclaw --match title,body --limit 50 -- "<frase clave>"
gh search issues --repo openclaw/openclaw --match comments --limit 50 -- "<frase de error o de mantenedor>"

Paso 4: Decidir el Resultado

Elige uno de estos resultados:

• not_duplicate
• duplicate_needs_judgment
• duplicate_confirmed

Usa duplicate_confirmed solo cuando la evidencia sea lo suficientemente sólida como para que el mantenedor pueda cerrar o reetiquetar de manera segura el elemento duplicado.

Usa duplicate_needs_judgment cuando:

• el problema parece el mismo pero el objetivo de implementación difiere
• la superposición de código es débil
• la redacción del issue es ambigua
• puede haber dos interpretaciones válidas del grupo de duplicados
• el objetivo parece intersecar dos grupos de duplicados existentes

Paso 5: Reutilizar o Crear un Grupo de prtags

Antes de crear un grupo, busca uno existente en prtags.

Comienza con búsqueda de texto sobre grupos:

prtags search text -R openclaw/openclaw "<frase del problema>" --types group --limit 10
prtags search similar -R openclaw/openclaw "<resumen del problema>" --types group --limit 10
prtags group list -R openclaw/openclaw

Inspecciona grupos probables:

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

Reutiliza un grupo existente cuando:

• representa el mismo problema
• ya contiene miembros claramente relacionados
• agregar el objetivo mantendría el grupo coherente

No amplíes un grupo existente solo porque gitcrawl colocó varios PRs o issues cerca uno del otro. Confirma que la ruta de implementación real y la intención del mantenedor aún coinciden antes de agregar el nuevo miembro.

Crea un nuevo grupo solo cuando ningún grupo existente encaje claramente.

Crea el grupo con un título basado en el problema y una descripción basada en la intención:

prtags group create -R openclaw/openclaw \
  --kind mixed \
  --title "<título centrado en el problema>" \
  --description "<misma intención, subsistema y ruta de resolución de duplicado>" \
  --status open

Luego adjunta el objetivo y cualquier miembro duplicado conocido:

prtags group add-pr <id-del-grupo> <número-del-pr>
prtags group add-issue <id-del-grupo> <número-del-issue>

Si un objetivo parece pertenecer ya a otro grupo de duplicados y no puedes reutilizar ese grupo de manera segura, detente. No crees un segundo grupo.

Paso 6: Asegurar que los Campos de Anotación Existan

Usa field ensure para que la habilidad sea idempotente.

Campos recomendados a nivel de objetivo:

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

Campos recomendados a nivel de grupo:

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

Paso 7: Guardar el Juicio del Mantenedor en prtags

Para un PR:

prtags annotation pr set -R openclaw/openclaw <número-del-pr> \
  duplicate_status=confirmed \
  duplicate_confidence=high \
  duplicate_rationale="<mismo problema, misma dirección de corrección, archivos y comentarios superpuestos>"

Para un issue:

prtags annotation issue set -R openclaw/openclaw <número-del-issue> \
  duplicate_status=confirmed \
  duplicate_confidence=high \
  duplicate_rationale="<mismo problema visible para el usuario y misma ruta de corrección prevista>"

Para el grupo:

prtags annotation group set <id-del-grupo> \
  duplicate_confidence=high \
  cluster_summary="<resumen del problema en una oración>" \
  duplicate_rationale="<por qué estos elementos pertenecen a un clúster de duplicados>"

Cuando la evidencia sea incompleta, establece duplicate_status=candidate y reduce la confianza.

Si una escritura de anotación por PR o por issue falla porque prtags no puede resolver el objetivo, no fuerces una ruta de escritura alternativa. Mantén el estado del grupo que pudiste escribir, reporta que el backend de curación aún no tiene el objeto objetivo y difiere el comando de sincronización de GitHub hasta que esté disponible.