Higiene de Cache do GitHub
Objetivo: responder perguntas comuns de leitura do GitHub primeiro a partir do gitcrawl e do shim gh, gastando chamadas ao vivo da API do GitHub apenas quando a atualização ou escritas importam.
Caminho Padrão
Use gh normalmente. Nas máquinas do Peter, espera-se que seja o shim baseado em gitcrawl, então leituras suportadas podem ser respondidas localmente ou em cache sem alterar comandos.
Prefira estas leituras locais/em cache:
gitcrawl sync owner/repo --numbers 123 --with pr-details
gh search issues "<termos>" -R owner/repo --state open --json number,title,state,url,updatedAt,labels,author
gh search prs "<termos>" -R owner/repo --state open --json number,title,state,url,updatedAt,isDraft,author
gh issue list -R owner/repo --state open --author usuario --assignee usuario --label bug --json number,title,url
gh pr list -R owner/repo --state open --author usuario --label dependencies --json number,title,url
gh issue view 123 -R owner/repo --json number,title,state,body,comments,labels,url
gh pr view 123 -R owner/repo --json number,title,state,body,comments,labels,files,commits,statusCheckRollup,url
gh pr checks 123 -R owner/repo --json name,state,detailsUrl,workflow
gh run list -R owner/repo --branch nome-da-branch --json databaseId,workflowName,status,conclusion,url
gh pr diff 123 -R owner/repo --patch
Use referências exatas e campos específicos. Evite loops amplos como um gh issue view por resultado quando um único gh search ou gh issue list --json ... pode responder a pergunta inicial.
Para CI, evite loops de polling apertados de gh run list / gh run view. Após um push ou workflow dispatch, identifique uma execução exata e então faça polling com backoff. Busque logs completos apenas para jobs com falha ou quando o usuário solicitar explicitamente logs. gh run view --log, --log-failed e endpoints comuns de log do Actions REST são cacheados por mais tempo pelo gitcrawl, enquanto o status da execução fica com cache curto.
Frescor
Respostas locais são boas para descoberta, busca de duplicatas, revisão de threads antigas, triagem por autor/rótulo e verificações do tipo "já existe um issue/PR sobre isso?" .
Use uma chamada ao vivo quando:
- escrevendo, comentando, fechando, mesclando, reexecutando ou editando
- verificando o estado final antes de uma ação de mantenedor
- confirmando status de CI após um push
- o resultado local está faltando ou obviamente desatualizado
- o usuário solicita o estado mais recente/atual
Para revisão de PR, prefira hidratar os detalhes exatos do PR uma vez com gitcrawl sync owner/repo --numbers <n> --with pr-details quando você sabe que irá inspecionar arquivos, commits, verificações ou resumos de execuções repetidamente. O shim gh pode hidratar automaticamente um PR exato em caso de falta, usando GITHUB_TOKEN ou gh auth token; hidratação explícita deixa intenção e custo mais claros.
Após uma escrita, faça uma leitura de volta direcionada, não uma varredura ampla.
XCache
Inspecione o comportamento do cache quando os limites de taxa forem suspeitos:
gh xcache stats
gh xcache keys
gh xcache gc
Leia backend_misses_by_command e backend_misses_by_route em gh xcache stats --json antes de adicionar novos loops ao vivo do GitHub. Esses mapas mostram quais formatos de comando ainda estão escapando do cache.
Use gh xcache flush apenas quando um fallback de cache desatualizado estiver enganando uma decisão.
Para prova apenas local, torne temporariamente o backend indisponível para um único comando:
GITCRAWL_GH_PATH=/tmp/no-real-gh gh search issues "<termos>" -R owner/repo --json number,title,url
Etiqueta do Agente
Agrupe perguntas por repositório e estado. Reutilize dados já exibidos na sessão. Faça backoff de polling de CI; inspecione logs apenas para execuções com falha ou a execução exata sob revisão. Não contorne o shim com /opt/homebrew/opt/gh/bin/gh a menos que esteja diagnosticando o próprio shim.