triage

Visão geral do triage skill

O que o triage faz

triage é um skill de triagem de issues no GitHub para fazer incoming issues avançarem por uma máquina de estados baseada em papéis. Ele ajuda você a classificar relatos, decidir se falta mais informação e encaminhar o trabalho para um agente AFK ou para um mantenedor humano. Se você precisa de um triage skill para Issue Tracking, a proposta aqui é reduzir adivinhação e manter o tratamento das issues consistente.

Para quem ele funciona melhor

Use o triage skill se você administra uma fila de issues movimentada, quer um processo de entrada repetível ou precisa de uma forma estruturada de transformar bugs confusos em trabalho acionável. Ele é especialmente útil quando você precisa separar bug de enhancement e depois mover cada issue para needs-triage, needs-info, ready-for-agent, ready-for-human ou wontfix.

O que o torna diferente

O principal diferencial é a combinação de uma máquina de estados explícita com disciplina de papéis. O skill não é apenas “resumir a issue”; ele espera exatamente um role de categoria e um role de estado, e inclui um requisito rígido de que todo comentário de triagem ou mensagem de issue comece com um aviso de divulgação. Isso importa se você precisa de saídas previsíveis, roteamento ciente de políticas e um fluxo de triagem que possa ser passado sem atrito para outro agente.

Como usar o triage skill

Instalação e primeira leitura

Instale com:

npx skills add mattpocock/skills --skill triage

Para a instalação do triage, comece por SKILL.md e depois leia AGENT-BRIEF.md e OUT-OF-SCOPE.md. Esses arquivos explicam o formato durável do brief e como ideias rejeitadas são registradas, que são as duas partes com maior chance de afetar a qualidade real da triagem. O repo não inclui scripts auxiliares nem pastas extras de referência, então esses três arquivos são o núcleo prático.

Dê ao skill a entrada certa

O uso do triage funciona melhor quando você fornece o título da issue, o corpo, quaisquer labels existentes e o objetivo exato da passada de triagem. Entradas fortes dizem ao skill se você quer classificação, mais informações, um brief para agente ou uma decisão final de rejeição.

Formato de prompt que funciona bem:

• “Faça a triagem desta issue do GitHub. Classifique como bug ou enhancement, escolha o role de estado correto e diga se ela deve ir para um agente AFK ou ficar com um humano.”
• “Aqui está a thread da issue e os labels atuais. Aplique a máquina de estados do triage e redija o comentário com o aviso obrigatório.”
• “Isso parece pouco especificado. Determine se pertence a needs-info ou ready-for-agent e explique quais critérios de aceitação estão faltando.”

Use o fluxo de trabalho, não só o label

Um guia prático de triagem é tratar a saída como roteamento, não como taxonomia. Primeiro confirme se a issue é um bug ou uma enhancement. Depois verifique se ela é acionável, se está bloqueada por informação do autor ou se está explicitamente fora de escopo. Se estiver pronta para trabalho de agente, o brief deve descrever expectativas de comportamento e critérios de aceitação, não caminhos de arquivo nem passos de implementação.

Fique atento às regras do repositório

Dois detalhes afetam de forma material a qualidade da saída: o requisito do aviso de divulgação e a regra de “exatamente um role de categoria mais um role de estado”. Se o estado da issue for ambíguo, o skill orienta a sinalizar o conflito e perguntar ao mantenedor antes de mudar qualquer outra coisa. Esse é o momento certo para parar e esclarecer, em vez de forçar um label.

Perguntas frequentes sobre o triage skill

O triage serve só para labels de issues do GitHub?

Não. O skill foi construído em torno de issue tracking no estilo GitHub, mas a função central é decidir o estado da issue e roteá-la. Se o seu tracker usa strings de label diferentes, os roles canônicos continuam importantes, e você os mapeia para o seu sistema antes de agir.

Preciso dele se consigo escrever um prompt normal?

Um prompt normal pode classificar uma issue, mas o triage skill acrescenta um modelo de estado repetível, um padrão de escrita de brief e um tratamento explícito de itens fora de escopo. Isso é valioso quando você quer consistência em muitas issues, e não apenas resumos pontuais.

O triage é amigável para iniciantes?

Sim, se você já entende labels básicos de issues. O triage skill é mais fácil de usar do que escrever um prompt de política sob medida porque ele diz quais estados existem e o que cada transição significa. O maior erro de iniciante é ignorar o contexto da issue e pedir um label sem corpo, sem discussão e sem estado atual.

Quando não devo usar o triage?

Não use o triage para planejamento profundo de implementação ou code review. Ele serve para intake, roteamento e decisões de prontidão. Se a issue já tem uma especificação completa e você precisa de ajuda de design ou código, outro skill ou um prompt direto de implementação é mais adequado.

Como melhorar o triage skill

Forneça mais contexto da issue

O triage skill melhora quando você inclui o corpo completo da issue, comentários visíveis, labels atuais e quaisquer notas do mantenedor. Um título isolado muitas vezes leva a um roteamento fraco porque o skill não consegue saber se o relato é reproduzível, se já foi respondido ou se faltam detalhes importantes.

Peça a decisão de que você realmente precisa

Se sua meta é “ready for agent”, diga isso. Se sua meta é “isso deve ser fechado como wontfix”, diga isso diretamente. O uso mais forte do triage é ser específico sobre a fronteira da decisão, porque assim o skill otimiza para o estado certo em vez de produzir um resumo genérico.

Melhore a qualidade do handoff

Quando uma issue for movida para ready-for-agent, peça um agent brief que registre o comportamento, as restrições e os critérios de aceitação em linguagem durável. Evite pedir instruções de implementação no nível de arquivo, a menos que você realmente precise delas; a orientação do repositório favorece contratos comportamentais porque eles sobrevivem à evolução do codebase.

Itere na primeira passada

Se a primeira triagem ficar muito cautelosa, refine com uma destas três adições: passos de reprodução, comportamento esperado versus comportamento atual, ou por que a issue importa para os usuários. Esses detalhes muitas vezes decidem se a issue deve ir para needs-info, ready-for-human ou wontfix, e deixam o triage skill mais assertivo na segunda passada.