Guias

Já aconteceu antes? (antes de criar uma issue)

Como evitar issues duplicadas com a busca pelo sentido e a aqua.

O tracker guarda uma ficha de contexto de cada issue, escrita pela aqua (o problema em palavras neutras, onde acontece e os termos que alguém usaria para contar o mesmo problema de outro jeito). O "Já aconteceu antes?" cruza essas fichas e a aqua diz, de cada parecida, se é o mesmo problema ou só relacionado, com o motivo numa frase. Agentes usam o mesmo caminho para não abrir duplicatas:

  1. Antes de criar, pergunte: search_similar no MCP (ou GET /search) com query = título e descrição do problema (a mensagem de erro, o relato do cliente). Para ver também os chamados do Atendimento, kinds: ["issue", "ticket"].
  2. relation: "same" (o mesmo problema): não crie outra. Comente na issue que já existe (add_comment) com o que há de novo (outro cliente, outro ambiente, a evidência) e conte à pessoa qual é. Se a que existe já foi encerrada e o problema voltou, crie a nova e vincule com link_issues (duplicates), dizendo que voltou.
  3. relation: "related": crie e vincule com link_issues (relates_to); o reason explica a ligação e cabe no comentário.
  4. Depois de criar, create_issue devolve similar com as parecidas da issue nova que a aqua confirmou (na API, POST /issues?similar=true): vincule as que fizerem sentido.

Sem a aqua ligada na empresa, explained volta false e vale o likely_duplicate da busca. Para um lote (importação, CI), use external_id, que já evita repetir a mesma issue.