Revisión Profunda de GitHub
Revisa como Peter: alta confianza, basada en evidencia, consciente del código, y dispuesto a decir "no probado" cuando el rastro es débil. El objetivo no es un resumen genérico. El objetivo es entender la clase de error, encontrar la causa real si es posible, decidir la mejor solución después de leer suficiente código, y señalar si una refactorización más grande mejoraría el diseño.
Inicio
Usa gh, no la navegación web, para referencias de GitHub:
gh issue view <n> --json number,title,state,author,body,comments,labels,updatedAt,url
gh pr view <n> --json number,title,state,author,body,comments,reviews,files,commits,statusCheckRollup,mergeStateStatus,headRefName,headRepositoryOwner,url
gh pr diff <n> --patch
Para PRs, recopila el contexto del autor por defecto a menos que el autor sea Peter (steipete o una cuenta obviamente propiedad de Peter). Usa el workflow local en ~/Projects/agent-scripts/skills/github-author-context/SKILL.md e incluye un breve bloque Author context: cerca de la parte superior de la revisión cuando el autor no sea Peter. Después de fusionar/rechazar/cerrar/revisar, usa ese mismo workflow de contexto del autor para agregar una nota del colaborador solo cuando la interacción cree una señal duradera para futuras revisiones.
Para la revisión local del repositorio, también inspecciona:
git status --short --branch
git fetch origin
git log --oneline --decorate -20
rg "<símbolo/error/config/endpoint clave>"
Si el repositorio tiene instrucciones locales, habilidades para issues/PRs, listas de documentación, guías de pruebas o manuales de mantenimiento, léelos antes de decidir.
Contrato de Revisión
Responde siempre a estas preguntas, explícitamente:
- URL/ref: número de issue o PR y superficie afectada.
- ¿Cuál es el error o comportamiento que se está corrigiendo?
- ¿Podemos identificar la causa raíz? En caso afirmativo, dónde en el código y por qué. En caso negativo, qué evidencia falta.
- Para regresiones, ¿quién/qué la introdujo y cuándo? Incluye la procedencia del commit/PR cuando sea trazable por historial acotado; di 'desconocido' en lugar de adivinar.
- ¿Es la solución actual/propuesta la mejor solución posible después de leer el código adyacente?
- ¿Una refactorización más grande mejoraría la corrección, claridad o mantenibilidad futura?
- ¿Qué evidencia existe: pruebas, reproducción en vivo, verificaciones de CI, documentación, documentación/fuente de dependencias, comportamiento enviado/actual.
- ¿Qué sigue siendo riesgoso o no verificado?
Profundidad de Lectura de Código
Lee más allá del primer archivo modificado. Sigue la ruta de llamada real:
- punto de entrada -> validación/parsing -> enrutamiento/despacho -> módulo propietario -> helper compartido -> límite de persistencia/red/tiempo de ejecución
- config/esquema/docs -> uso en tiempo de ejecución -> ruta de doctor/migración/solución
- código propietario de proveedor/canal/plugin -> unión genérica del núcleo, solo si varios propietarios lo necesitan
- pruebas alrededor de la superficie tocada más las pruebas de regresión adyacentes
Cuando el comportamiento dependa de una dependencia, lee la documentación/fuente/tipos o el contrato del paquete actual antes de asumir.
Prefiere la fuente actual y la evidencia ejecutable sobre los comentarios de los issues. Trata los comentarios obsoletos, CI antiguo y comportamiento de versiones anteriores como pistas hasta que se vuelvan a verificar.
Procedencia
Para revisiones de errores/regresiones, incluye una respuesta compacta Procedencia: cuando sea factible:
- Usa
git log -S/-G,git blame, PRs/issues enlazados y pruebas. - Separa el autor, el committer/fusionador y el autor del PR actual cuando difieran.
- Redacta como
introducido por,hecho visible poroarrastrado por. - Incluye confianza:
claro,probableodesconocido. - Para características, documentación, refactorizaciones o errores no trazables, escribe
N/Ao di qué evidencia falta.
Nivel de Calidad de la Solución
Las buenas soluciones generalmente:
- viven en el límite de propiedad donde pertenece el error
- preservan el comportamiento público/compatible hacia atrás a menos que el issue trate de retirarlo
- agregan una prueba de regresión en el punto más pequeño con significado
- evitan casos especiales amplios, migraciones ocultas, centinelas semánticos e identificadores de proveedor/canal en el núcleo genérico
- actualizan la documentación/changelog cuando el comportamiento visible para el usuario cambia
- fallan claramente en rutas de tiempo de ejecución y se reparan a través de rutas de doctor/migración cuando ese es el contrato establecido
Señala cuando una solución es solo a nivel de síntomas. Si una refactorización un poco más grande hace que el invariante sea obvio y reduce errores futuros, recomiéndala. Si la refactorización amplía el riesgo sin mejorar la clase de error, dilo.
Forma de Revisión de PR
Lidera con hallazgos al revisar un PR. Los hallazgos necesitan referencias de archivo/línea/símbolo y un modo de fallo concreto. Evita comentarios vagos de "considerar".
Si no hay problemas bloqueantes:
- di que no se encontraron problemas bloqueantes de corrección
- enumera la evidencia más fuerte verificada
- nombra el riesgo residual / las brechas de prueba
- responde si el diseño es la mejor forma disponible
No apruebes, comentes, cierres, fusiones, hagas push o desembarques a menos que el usuario haya solicitado esa acción.
Forma de Revisión de Issues
Para errores/issues:
- Reconstruye el escenario del reportante y la versión/superficie afectada.
- Verifica si
mainactual ya lo soluciona. - Reproduce o crea una prueba local/en vivo mínima cuando sea factible.
- Si está claro, identifica la causa raíz y la solución propuesta.
- Si está resuelto en
main, solo comenta/cierra cuando el usuario lo pida; incluye la prueba y el commit/PR canónico si se conoce.
Si la reproducción no es factible, di exactamente qué lo bloquea y qué evidencia haría confiable la decisión.
Plantilla de Salida
Usa esta forma cuando el usuario pregunte "de qué se trata", "es esta la mejor solución" o "qué se solucionó":
Ref: #123 / PR #456
Superficie: <tiempo de ejecución/CLI/proveedor/canal/docs>
Error: <una o dos oraciones>
Causa: <ruta de código + confianza>
Procedencia: <introducido/hecho visible/arrastrado por commit/PR/fecha, o N/A/desconocido>
Mejor solución: <qué debería cambiar y por qué>
Refactor: <sí/no, forma específica>
Prueba: <pruebas/en vivo/CI/fuente/documentación de dependencias>
Riesgo: <incertidumbre restante>
Mantenlo conciso, pero no te saltes las decisiones de causa/solución/refactor/prueba.