GitHub Issue Query: issues filtradas antes da análise

ANÁLISE EDITORIAL

Consultar uma fila de issues parece simples até o repositório acumular centenas de itens, corpos longos, comentários e rótulos inconsistentes. A GitHub Issue Query transforma esse trabalho em uma sequência pequena: escolher o repositório, limitar o estado e a quantidade, buscar campos estruturados com a GitHub CLI e reduzir a saída com uma expressão jq.

O detalhe mais útil está no comportamento padrão. Sem --jq, o helper não despeja o conteúdo completo na conversa. Ele informa quantidade, tamanho e esquema, para que a próxima consulta seja mais específica. Isso reduz ruído, mas não elimina o risco de ler dados privados. A conta autenticada, o host e o repositório ainda precisam ser conferidos antes do primeiro comando.

Imagem: Ilustração editorial exclusiva do Bastidores da IA sobre cartões de issues atravessando filtros até uma saída estruturada e protegida. Não é captura de tela, interface real, logotipo oficial, consulta executada nem prova de acesso a um repositório.

O que esta Skill faz de verdade

O SKILL.md fixado no commit auditado ensina o agente a chamar um helper Bash chamado query-issues.sh. O script usa gh issue list, pede um conjunto definido de campos JSON e, quando há um filtro, entrega esse JSON ao jq. Não cria, edita, fecha, reabre, rotula ou comenta issues.

Os parâmetros documentados são --repo, --state, --limit e --jq. Sem repositório explícito, a GitHub CLI tenta usar o repositório atual. O estado padrão é open e o limite padrão é 30. A lista de campos inclui número, título, estado, autor, datas, corpo, rótulos, responsáveis, comentários, marco, URL e projetos.

O helper oficial foi lido estaticamente nesta curadoria e não foi executado. Ele mantém os argumentos entre aspas ao chamar gh e jq, mas não valida antecipadamente se estado e limite têm formatos aceitáveis. Esses erros são devolvidos pelas ferramentas de linha de comando.

Para quem serve

A Skill serve para mantenedores, equipes de suporte, gestores de produto e desenvolvedores que precisam responder perguntas delimitadas sobre uma fila existente. Exemplos seguros são listar número e título dos dez itens abertos mais recentes, localizar issues com um rótulo conhecido, identificar itens antigos para triagem ou contar estados depois de obter uma amostra adequada.

Ela é especialmente útil quando o agente tende a pedir todos os campos antes de saber de quais realmente precisa. O modo sem --jq oferece um ponto de partida econômico: revela o formato e o volume sem imprimir cada corpo e comentário. Depois, a pessoa escolhe um filtro que devolva somente as colunas necessárias.

Não é uma ferramenta de análise automática de prioridade, severidade ou intenção. Rótulos podem estar ausentes, títulos podem ser vagos e comentários podem contradizer o corpo inicial. Também não substitui a visualização da issue original quando a decisão depende de contexto, anexos, links, histórico ou conversas recentes.

Compatibilidade e pré-requisitos

O uso funcional exige um ambiente Bash, a GitHub CLI gh autenticada e jq. Em Linux e macOS, o helper pode ser executado no shell comum. No Windows, use WSL ou outro ambiente Bash compatível e confirme que gh e jq pertencem ao mesmo ambiente e conseguem acessar o repositório pretendido.

A documentação oficial de gh auth status mostra como verificar a conta e o estado de autenticação. Se a CLI ainda não estiver autenticada, consulte gh auth login e escolha conscientemente o host, o protocolo e o método de credencial. Não cole tokens em prompts, arquivos de Skill ou histórico de shell.

O filtro segue a linguagem do manual oficial do jq. Uma expressão incorreta pode falhar, retornar nada ou produzir uma seleção enganosa. Antes de adotar um filtro complexo, teste uma amostra pequena e confira manualmente duas ou três issues na interface do GitHub.

Instalação recomendada

Para preservar a versão auditada, clone a fonte oficial e fixe o commit:

git clone https://github.com/github/gh-aw.git
cd gh-aw
git checkout 398b1c9247189c14f57c9d63a056d516ad327d39

Depois, revise a pasta .github/skills/github-issue-query e copie a pasta completa para o diretório de Skills reconhecido pelo seu agente. A pasta funcional contém o SKILL.md e o helper. Em sistemas POSIX, confirme a permissão de execução do script. No Windows, mantenha o arquivo dentro do ambiente Bash escolhido.

A pasta oficial fixada é a referência de instalação funcional. O ZIP hospedado pelo Bastidores é documental e não contém query-issues.sh, o runtime do GitHub Agentic Workflows ou dependências. Essa separação evita redistribuir um script executável no catálogo.

Configuração antes do primeiro uso

Comece confirmando a identidade ativa com gh auth status. Se houver mais de um host ou conta, valide qual deles será usado. Uma credencial capaz de ler repositórios privados amplia o alcance da consulta, mesmo que o comando seja somente leitura. Escolha o menor escopo necessário e não use uma conta pessoal ampla em uma automação compartilhada.

Defina o repositório no comando inicial, mesmo quando o diretório atual já parece correto. O formato owner/repo torna a intenção visível na revisão e reduz a chance de consultar o projeto errado. Também escolha um limite pequeno. Dez itens são suficientes para validar campos, rótulos e formato antes de aumentar o volume.

Por fim, escreva o objetivo da consulta em uma frase. “Encontrar issues abertas com o rótulo bug e devolver número, título e URL” é verificável. “Analise o backlog” é amplo demais e pode induzir coleta excessiva. O guia do Bastidores sobre permissões de agentes ajuda a separar leitura, rede, escrita e ações externas.

Primeiro uso seguro

O primeiro comando deve conferir somente esquema e tamanho. Substitua owner/repo por um repositório que você está autorizado a consultar:

gh auth status
./query-issues.sh --repo owner/repo --state open --limit 10

Leia item_count, data_size_bytes e os campos listados. Essa saída confirma que a consulta alcançou um repositório e recebeu JSON, mas não prova que a conta, o host ou o conjunto de itens eram os pretendidos. Confira esses três pontos antes de solicitar dados.

Em seguida, devolva apenas número, título e URL:

./query-issues.sh --repo owner/repo --state open --limit 10 --jq '.[] | {number, title, url}'

Compare dois resultados com as respectivas páginas. Só depois crie filtros por autor, rótulo, responsáveis, comentários ou datas. Evite --jq '.' em repositórios privados ou grandes, pois essa opção pede todos os campos coletados, incluindo corpo e informações de comentários.

Resultado esperado

Sem filtro, o resultado esperado é um objeto JSON curto com uma mensagem, quantidade de itens, tamanho aproximado dos dados, esquema dos campos e sugestões de consulta. Esse modo não mostra o conteúdo completo das issues, embora o helper já tenha recebido a resposta da GitHub CLI na memória do processo para calcular tamanho e esquema.

Com filtro, o resultado esperado é o JSON produzido pelo jq. Uma consulta de títulos deve retornar poucos objetos com número e título. Uma contagem por estado deve devolver agrupamentos. Um filtro sem correspondência pode produzir saída vazia, o que significa apenas que a amostra consultada e a expressão não encontraram itens.

A página de gh issue list é a fonte principal para opções, campos JSON e comportamento atual da CLI. Releia essa documentação quando atualizar gh ou modificar o helper, pois campos e limites podem mudar.

Permissões e riscos

O helper realiza consulta, mas a credencial pode enxergar mais do que o pedido precisa. Corpos, comentários, nomes de usuários, rótulos internos, marcos e projetos podem revelar falhas ainda não divulgadas, dados pessoais, clientes, infraestrutura ou planos de produto. Minimize campos, limite o repositório e não cole a saída integral em serviços não autorizados.

A ausência de --jq reduz a resposta exibida, mas não impede que o processo local obtenha os campos definidos no comando gh issue list. Para uma fronteira de dados mais rigorosa, revise o helper e reduza JSON_FIELDS antes da consulta. Faça a alteração em uma cópia versionada e registre por que cada campo é necessário.

Uma expressão jq pode produzir conclusões erradas sem causar erro técnico. Por exemplo, um rótulo ausente não significa que a issue não pertence à categoria, e contar comentários não mede importância. Trate filtros como seleção de dados, não como julgamento editorial ou priorização automática.

O script auditado não escreve no GitHub. Ainda assim, um agente com outras ferramentas pode tentar agir depois de ler a fila. Separe a etapa de consulta de qualquer comentário, alteração de rótulo, fechamento ou atribuição. Exija confirmação explícita para cada ação externa.

Erros comuns

• Omitir o repositório: o diretório atual pode apontar para outro projeto. Informe --repo owner/repo.
• Usar a conta errada: confirme host e identidade com gh auth status.
• Começar com todos os dados: use primeiro o modo sem --jq e um limite pequeno.
• Tratar --jq '.' como inofensivo: ele pode devolver corpos, comentários e metadados desnecessários.
• Confiar em rótulos como verdade completa: valide uma amostra na interface original.
• Esperar uma análise pronta: a Skill consulta e transforma JSON, não decide prioridade ou severidade.
• Rodar no PowerShell puro: o helper é Bash. Use um ambiente compatível ou adapte em uma cópia revisada.
• Ignorar jq ausente: confirme a instalação antes de atribuir uma saída vazia ao repositório.
• Compartilhar tokens ou resultados privados: mantenha credenciais fora de prompts e reduza os campos.
• Tratar o ZIP local como instalador: o download do Bastidores é documental e não contém o helper.

Versão auditada e download local

A curadoria fixou o commit 398b1c9247189c14f57c9d63a056d516ad327d39. Em 24/08/2026, o repositório oficial github/gh-aw tinha 4.989 estrelas e não estava arquivado. A adoção observável ajuda na curadoria, mas não substitui revisão de conteúdo, permissões ou mudanças futuras.

A licença MIT permite redistribuição sob suas condições. O ZIP local tem 3.035 bytes, contém somente SKILL.md, LICENSE e ORIGEM.md, e possui SHA-256 689f4d6cb746477418fcc1aa38a46067dd0e425d99db5527f95cefaa7bd10039. Os arquivos SKILL.md e LICENSE preservam exatamente os bytes do commit fixado.

Resultado esperado e limite final

GitHub Issue Query é uma boa referência para consultas menores e verificáveis. O melhor primeiro resultado não é um resumo de todo o backlog. É a confirmação da conta, do host e do repositório, seguida por esquema, tamanho e uma seleção curta de campos que uma pessoa consegue conferir.

Considere o teste concluído quando o comando usou um repositório explícito, trouxe no máximo dez itens, devolveu apenas número, título e URL e duas entradas foram comparadas com a fonte. Se o próximo passo exigir classificação, documente critérios separados e preserve links para evidência. Se exigir escrita, abra uma nova etapa com confirmação humana.

O download local permite auditar a instrução e a licença sem receber código executável. O botão do repositório oficial leva à pasta que contém o helper necessário para uso real. Mantenha as duas ações distintas: o ZIP não consulta issues, e uma lista filtrada não é autorização para alterar o repositório.

Fontes primárias

• Repositório oficial github/gh-aw
• Pasta da Skill no commit auditado
• SKILL.md oficial fixado
• Helper oficial auditado estaticamente
• Licença MIT preservada
• Manual oficial de gh issue list
• Manual oficial de gh auth status
• Manual oficial de gh auth login
• Manual oficial do jq