tag-duplicate-prs-issues

Marcar PRs e Issues Duplicados

Use esta skill quando um mantenedor precisar decidir se um pull request ou issue é uma duplicata de trabalho existente.

Esta skill é para triagem e agrupamento de mantenedores. Não é para revisar a qualidade da implementação de um PR.

Configuração Necessária

Não escreva grupos duplicados ou anotações até que esta configuração esteja completa. A descoberta somente leitura ainda pode prosseguir com gitcrawl e gh ao vivo.

Skills Complementares

Use $gitcrawl primeiro para descoberta local de candidatos. Use a skill prtags do repositório prtags em skills/prtags/SKILL.md quando estiver disponível.

Instalar os CLIs

Instale prtags a partir da versão fixada abaixo. Não confie em uma compilação local antiga, a menos que o mantenedor queira explicitamente testar comportamento não lançado.

Caminho de instalação do CLI prtags:

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

prtags está fora da organização OpenClaw, então esta instalação permanece fixada em uma versão revisada que o proxy do módulo Go resolve e o banco de dados público de soma de verificação verifica. GOBIN mantém o executável instalado no mesmo diretório local do usuário que o instalador anterior, para que um caminho PATH existente $HOME/.local/bin continue a resolver a versão recém-instalada. Não instale executando um script remoto em um shell, e não aponte a instalação para um branch: qualquer um executa o que o terceiro servir em tempo de execução, com os privilégios do próprio mantenedor. Mover para uma versão mais nova de prtags é uma alteração revisada neste arquivo, não uma etapa intermediária.

Autenticar prtags

prtags deve estar logado com a conta GitHub do próprio mantenedor através do fluxo de dispositivo OAuth. Não use um token de mantenedor compartilhado para triagem interativa.

prtags auth login
prtags auth status

O resultado esperado é que prtags armazene a identidade do mantenedor logado localmente e use essa conta para gravações autenticadas.

Regra de Configuração Ausente

Não exija uma verificação prévia antes de iniciar o fluxo de trabalho. Prossiga com as etapas normais até que você realmente precise de uma ferramenta ou estado de conta.

Assim que você descobrir que prtags está ausente ou não logado na etapa de gravação, pare imediatamente. Não continue em modo de gravação parcial após esse ponto.

Se prtags estiver ausente, peça ao usuário para executar o comando de instalação fixada de Instalar os CLIs. Mantenha essa seção como a fonte única da versão instalada; não improvise outro caminho de instalação.

Se prtags auth status mostrar que o usuário não está logado, peça ao usuário para executar:

prtags auth login

Retome apenas depois que a ferramenta ausente ou o estado de login tiver sido corrigido.

Padrão de Caminho de Leitura

Para descoberta de candidatos neste fluxo de trabalho, use gitcrawl primeiro. Trate-o como a camada local de histórico e agrupamento para issues relacionadas, tentativas de duplicatas e threads fechadas.

Use gh ao vivo ou gh api para o thread alvo e para qualquer candidato antes de fazer um julgamento acionável. Use GitHub ao vivo quando gitcrawl estiver ausente ou desatualizado por um motivo concreto, como:

• o alvo ou candidato ainda não está presente
• os dados locais estão claramente desatualizados ou incompletos para a decisão que você precisa tomar
• gitcrawl erra, expira ou não tem os dados de vizinho/pesquisa necessários

Quando você recorrer à pesquisa ao vivo do GitHub, observe que fez isso e por quê.

Se uma gravação posterior do nível alvo do prtags falhar porque seu próprio espelho não acompanhou, pare e informe que o backend de curadoria está faltando o objeto alvo, em vez de forçar uma gravação alternativa.

Objetivo

Para cada PR ou issue alvo:

1. coletar evidências de duplicata
2. decidir se é uma duplicata real
3. criar ou reutilizar um grupo prtags para aquele cluster de duplicatas
4. salvar o julgamento do mantenedor em prtags
5. confiar nas gravações normais do grupo prtags para impulsionar a sincronização de comentários do GitHub quando essa integração estiver configurada

Papéis das Ferramentas

Use as ferramentas com estes limites:

• gitcrawl é geração de candidatos e contexto histórico
  • use-o primeiro para pesquisa local de título/corpo, vizinhos, clusters e descoberta de threads fechadas
  • trate cada candidato como uma pista até que o GitHub ao vivo confirme
• gh é a verdade ao vivo do GitHub
  • use-o para estado alvo, corpo, comentários, revisões, arquivos, issues vinculados e status atual aberto/fechado/mesclado
  • use gh search apenas quando gitcrawl estiver desatualizado, faltando dados ou não puder expressar a consulta necessária
• prtags é a camada de curadoria do mantenedor
  • use-o para criar ou reutilizar um grupo de duplicatas
  • use-o para salvar o status de duplicata, confiança, justificativa e resumo do grupo
  • use-o como a fonte da verdade para o comentário do grupo voltado para o GitHub

Regras de Trabalho

• Não chame algo de duplicata apenas porque os títulos são semelhantes.
• Não chame algo de duplicata apenas porque os mesmos arquivos foram alterados.
• Um cluster de duplicatas deve ser baseado no mesmo problema voltado para o usuário, na mesma intenção e em contexto de implementação ou investigação substancialmente sobreposto.

Regra de Um Grupo

Trate grupos de duplicatas como exclusivos. Um PR ou issue deve pertencer a no máximo um grupo de duplicatas por vez.

Isso significa:

• antes de criar um novo grupo, pesquise se já existe um grupo que represente a mesma história de duplicata
• se o alvo já parece pertencer a um grupo de duplicatas diferente, pare e resolva esse conflito primeiro
• não crie um segundo grupo para o mesmo alvo apenas porque a redação é ligeiramente diferente
• se dois grupos existentes plausíveis se sobrepõem e você não pode mesclar o julgamento com segurança, pare e pergunte ao mantenedor

Esta regra importa mais do que velocidade. A skill deve manter um cluster de duplicatas coerente por problema, não muitos clusters quase duplicados.

O Que Um Bom Grupo de Duplicatas Representa

Um grupo de duplicatas deve descrever o problema subjacente e a direção da correção pretendida. Não agrupe itens apenas porque compartilham uma palavra-chave.

Boa forma de grupo:

• mesmo bug voltado para o usuário ou mesma tarefa voltada para o mantenedor
• mesmo subsistema ou superfície de código
• mesma direção de alteração pretendida
• mesmo caminho provável de resolução de duplicata

Forma ruim de grupo:

• "todos os PRs que tocam no Slack"
• "todas as issues mencionando retry"
• "todos os itens relacionados a auth"

O título do grupo deve nomear o problema real. A descrição do grupo deve resumir a intenção e a superfície de código.

Exemplos:

• gateway: regressão de inicialização do bootstrap de status de canal
• whatsapp: tratamento de tempo limite de preflight QR
• release: lacunas de handoff de validação entre sistemas operacionais

Lista de Verificação de Evidências

Antes de declarar uma duplicata, colete evidências de pelo menos duas categorias. Vizinhos de gitcrawl, resultados de pesquisa e associação a cluster contam como geração de candidatos, não como prova suficiente por si só.

Para PRs:

• mesma declaração de problema ou quase a mesma
• mesmos arquivos alterados ou intervalos de arquivos sobrepostos
• mesma direção de correção
• mesmo subsistema e modo de falha
• mesma issue vinculada ou mesmo sintoma visível ao usuário

Para issues:

• mesmo problema visível ao usuário
• mesma história de reprodução ou mesmo modo de falha
• mesma área provável de correção
• mesmos PRs já vinculados ou discutidos
• mesmos mantenedores já direcionando para o mesmo agrupamento de duplicatas

Se você tiver apenas semelhança de redação, isso não é suficiente.

Etapa 1: Ler o Alvo

Comece lendo o alvo em si. Use GitHub ao vivo para o estado atual do alvo.

Para um PR:

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

Para uma issue:

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

Registre:

• tipo e número do alvo
• título
• declaração do problema
• intenção proposta
• subsistema
• se está aberto, fechado ou mesclado
• se já existe um thread de duplicata provável mencionado por humanos

Etapa 2: Pesquisar Amplamente com Gitcrawl

Use gitcrawl primeiro porque é a fonte local de histórico e agrupamento do OpenClaw. Não mude para pesquisa ampla ao vivo do GitHub, a menos que gitcrawl esteja faltando dados, desatualizado ou falhando.

Comece com o alvo e threads próximos:

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

Em seguida, pesquise frases-chave e termos de subsistema:

gitcrawl search openclaw/openclaw --query "<frase-chave do título ou corpo>" --mode hybrid --limit 20 --json
gitcrawl search openclaw/openclaw --query "<subsistema ou frase de erro>" --mode hybrid --limit 20 --json

Inspecione clusters prováveis:

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

Para PRs, verifique a sobreposição provável de código com dados de arquivo ao vivo:

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

Para issues, verifique o estado da issue duplicata provável e os comentários ao vivo:

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

Etapa 3: Usar Pesquisa ao Vivo do GitHub para Lacunas

Use pesquisa ao vivo direcionada do GitHub após gitcrawl quando:

• o alvo for muito novo para o armazenamento local
• comentários ou revisões importarem e o armazenamento local não os tiver
• a frase exata não apareceu nos resultados locais, mas a issue/PR é recente o suficiente para que o GitHub deva conhecê-la

gh search prs --repo openclaw/openclaw --match title,body --limit 50 -- "<frase-chave>"
gh search issues --repo openclaw/openclaw --match title,body --limit 50 -- "<frase-chave>"
gh search issues --repo openclaw/openclaw --match comments --limit 50 -- "<erro ou frase do mantenedor>"

Etapa 4: Decidir o Resultado

Escolha um destes resultados:

• not_duplicate
• duplicate_needs_judgment
• duplicate_confirmed

Use duplicate_confirmed apenas quando a evidência for forte o suficiente para que o mantenedor possa fechar ou reetiquetar com segurança o item duplicado.

Use duplicate_needs_judgment quando:

• o problema parece o mesmo, mas o objetivo da implementação difere
• a sobreposição de código é fraca
• a redação da issue é ambígua
• pode haver duas interpretações válidas de grupo de duplicatas
• o alvo parece cruzar dois grupos de duplicatas existentes

Etapa 5: Reutilizar ou Criar Um Grupo prtags

Antes de criar um grupo, pesquise prtags por um existente.

Comece com pesquisa de texto em grupos:

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

Inspecione grupos prováveis:

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

Reutilize um grupo existente quando:

• ele representa o mesmo problema
• já contém membros claramente relacionados
• adicionar o alvo manteria o grupo coerente

Não amplie um grupo existente apenas porque gitcrawl colocou vários PRs ou issues próximos uns dos outros. Confirme se o caminho real de implementação e a intenção do mantenedor ainda correspondem antes de adicionar o novo membro.

Crie um novo grupo apenas quando nenhum grupo existente se encaixar claramente.

Crie o grupo com um título baseado no problema e uma descrição baseada na intenção:

prtags group create -R openclaw/openclaw \
  --kind mixed \
  --title "<título centrado no problema>" \
  --description "<mesma intenção, subsistema e caminho de resolução de duplicata>" \
  --status open

Em seguida, anexe o alvo e quaisquer membros duplicados conhecidos:

prtags group add-pr <id-do-grupo> <numero-do-pr>
prtags group add-issue <id-do-grupo> <numero-da-issue>

Se um alvo parece já pertencer a outro grupo de duplicatas e você não pode reutilizar esse grupo com segurança, pare. Não crie um segundo grupo.

Etapa 6: Garantir que os Campos de Anotação Existam

Use field ensure para que a skill seja idempotente.

Campos recomendados no nível do alvo:

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 no nível do 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

Etapa 7: Salvar o Julgamento do Mantenedor em prtags

Para um PR:

prtags annotation pr set -R openclaw/openclaw <numero-do-pr> \
  duplicate_status=confirmed \
  duplicate_confidence=high \
  duplicate_rationale="<mesmo problema, mesma direção de correção, arquivos e comentários sobrepostos>"

Para uma issue:

prtags annotation issue set -R openclaw/openclaw <numero-da-issue> \
  duplicate_status=confirmed \
  duplicate_confidence=high \
  duplicate_rationale="<mesmo problema visível ao usuário e mesmo caminho de correção pretendido>"

Para o grupo:

prtags annotation group set <id-do-grupo> \
  duplicate_confidence=high \
  cluster_summary="<resumo do problema em uma frase>" \
  duplicate_rationale="<por que esses itens pertencem a um cluster de duplicatas>"

Quando a evidência estiver incompleta, defina duplicate_status=candidate e reduza a confiança.

Se uma gravação de anotação por PR ou por issue falhar porque prtags não pode resolver o alvo, não force um caminho de gravação alternativo. Mantenha o estado do grupo que você conseguiu gravar, informe que o backend de curadoria ainda está faltando o objeto alvo e adie a decisão final para um momento posterior.

Etapa 8: Relatar o Resultado

Após salvar todas as anotações, relate ao mantenedor:

• qual número de PR ou issue foi avaliado
• o resultado (not_duplicate, duplicate_needs_judgment, duplicate_confirmed)
• qual grupo de duplicatas (novo ou existente) foi usado, com link para ele
• quais campos de anotação foram definidos
• se alguma etapa foi adiada devido a dados ausentes, estado de login ou conflitos de grupo

Quando você relatou uma duplicata confirmada, o mantenedor pode então fechar o item ou reetiquetá-lo manualmente. Não feche PRs ou issues automaticamente.