Higiene del Caché de GitHub
Objetivo: responder primero las preguntas comunes de lectura de GitHub desde gitcrawl y el shim gh, y gastar llamadas a la API de GitHub en vivo solo donde la frescura o las escrituras sean importantes.
Ruta Predeterminada
Usa gh de forma normal. En las máquinas de Peter, se espera que sea el shim respaldado por gitcrawl, por lo que las lecturas compatibles pueden responderse localmente o en caché sin cambiar los comandos.
Prefiere estas lecturas locales/en caché:
gitcrawl sync owner/repo --numbers 123 --with pr-details
gh search issues "<términos>" -R owner/repo --state open --json number,title,state,url,updatedAt,labels,author
gh search prs "<términos>" -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 nombre-rama --json databaseId,workflowName,status,conclusion,url
gh pr diff 123 -R owner/repo --patch
Usa referencias exactas y campos reducidos. Evita bucles amplios como un gh issue view por resultado cuando un solo gh search o gh issue list --json ... puede responder la pregunta inicial.
Para CI, evita bucles de sondeo intensivos con gh run list / gh run view. Después de un push o un workflow dispatch, identifica una ejecución exacta y luego sondea con backoff. Obtén los registros completos solo para trabajos fallidos o cuando el usuario los solicite explícitamente. Los registros de tipo completado (gh run view --log, --log-failed) y los endpoints REST comunes de Actions se almacenan en caché por más tiempo en gitcrawl, mientras que el estado de la ejecución permanece de corta duración.
Frescura
Las respuestas locales son buenas para descubrimiento, búsqueda de duplicados, revisión de hilos antiguos, triaje por autor/etiqueta y comprobaciones de "¿es probable que ya exista un issue/PR?".
Usa una llamada en vivo cuando:
- escribas, comentes, cierres, fusiones, reejecuciones o ediciones
- verifiques el estado final actual antes de una acción de mantenedor
- verifiques el estado de CI después de un push
- el resultado local falte o esté claramente desactualizado
- el usuario solicite el estado más reciente/en vivo
Para revisión de PR, prefiere hidratar los detalles exactos del PR una vez con gitcrawl sync owner/repo --numbers <n> --with pr-details cuando sepas que inspeccionarás archivos, commits, comprobaciones o resúmenes de ejecución repetidamente. El shim gh puede auto-hidratar un PR exacto en caso de fallo, usando GITHUB_TOKEN o gh auth token; la hidratación explícita hace más claros la intención y el costo.
Después de una escritura, realiza una lectura de verificación dirigida, no un resaneo amplio.
XCache
Inspecciona el comportamiento del caché cuando se sospechen límites de tasa:
gh xcache stats
gh xcache keys
gh xcache gc
Lee backend_misses_by_command y backend_misses_by_route en gh xcache stats --json antes de agregar nuevos bucles en vivo de GitHub. Esos mapas muestran qué formas de comando aún están escapando del caché.
Usa gh xcache flush solo cuando una respuesta de respaldo en caché desactualizada esté generando una decisión engañosa.
Para una prueba solo local, haz que el backend no esté disponible temporalmente para un solo comando:
GITCRAWL_GH_PATH=/tmp/no-real-gh gh search issues "<términos>" -R owner/repo --json number,title,url
Etiqueta del Agente
Agrupa las preguntas por repositorio y estado. Reutiliza los datos ya mostrados en la sesión. Realiza backoff en el sondeo de CI; inspecciona los registros solo para ejecuciones fallidas o la ejecución exacta bajo revisión. No omitas el shim con /opt/homebrew/opt/gh/bin/gh a menos que estés diagnosticando el propio shim.