gitpodium — auditoría interactiva de contribuciones
Tú (el agente) ejecutas esto de principio a fin. El usuario nunca debería tener que escribir un comando.
Plantea la configuración como una breve entrevista, confirma un plan, ejecuta el pipeline, entrega el
informe, y siempre indica la advertencia. Haz preguntas en lotes pequeños (usa
AskUserQuestion en Claude Code); no interrogues línea por línea.
GP a continuación = la ruta al directorio de esta skill. Cada paso escribe artefactos en el
directorio de salida elegido por el usuario (GITPODIUM_OUT, por defecto el directorio actual).
Paso 0 — Prerrequisitos (haz esto antes de preguntar cualquier otra cosa)
gh auth status— si no está autenticado, dile al usuario que ejecutegh auth login(en Claude Code pueden escribir! gh auth login). Ámbitos de token requeridos:repo(repos privados) yread:org(listar repos de la org). Vuelve a verificar antes de continuar.- Confirma que
git,python3,bash,awkexisten (estándar en macOS/Linux). Detente y reporta si faltaghopython3.
Solo continúa una vez que gh auth status esté en verde.
Paso 1 — Alcance (qué auditar)
Pregunta al usuario:
- ¿Qué propietarios de GitHub? Una o más orgs y/o usuarios (ej.
acme-inc acme-labs). Los repos propios de un usuario también funcionan. Ofrece ejecutargh org list/gh repo list <propietario> --limit 5para ayudarles a confirmar los nombres correctos. - ¿Propietario completo o un subconjunto? Si solo quieren repos específicos, recoge una
lista
propietario/repoy usa un archivo de repos en lugar de una org completa. - Recuerda: los repos privados se incluyen solo si su token
ghpuede verlos.
Mapa → argumentos de clone, o un archivo -f repos.txt.
Paso 2 — Métrica de ranking
Pregunta: ¿clasificar por qué métrica? (el informe HTML siempre permite a los espectadores cambiar en vivo; esto establece la vista predeterminada y el titular que reportas):
| Opción | Significado |
|---|---|
churn (predeterminado) | líneas añadidas + eliminadas — más común "cuánto código se movió" |
commits | número de commits — actividad/cadencia, menos manipulable por grandes refactorizaciones |
added / deleted | crecimiento vs. limpieza |
net | añadidas − eliminadas |
repos | amplitud (cuántos repos tocó) |
Mapa → GITPODIUM_METRIC=<opción> (se pasa a la construcción del informe). Esto clasifica la vista de git churn.
El informe también incluye una pestaña de Colaboración (próximo párrafo) con sus propias métricas de GitHub —
no es necesario elegir entre ambas, ambas se construyen.
También se recopila: colaboración en GitHub (PRs, revisiones, issues)
Además del historial de git, gitpodium extrae pull requests, revisiones de código, comentarios de revisión e
issues de la API de GitHub (gitpodium github) en una segunda pestaña de Colaboración,
clave por inicio de sesión de GitHub. Este es el trabajo que el churn no ve — un revisor intensivo que
escribe poco código finalmente rankea. Menciónalo cuando presentes el informe. Advertencias a transmitir:
- Necesita la API de
ghy solo cubre repos alojados en GitHub que el token puede ver; está sujeto al límite de tasa de GraphQL. EstableceGITPODIUM_SKIP_GITHUB=1para omitirlo (repos no GitHub, o para autorizar límite de tasa). - Issues pueden estar casi vacíos si el equipo usa Jira/Linear — eso es esperado, no un error.
- Los bots (actores tipo
Botde GraphQL,*[bot],extra_bots) también se excluyen de los revisores.
Paso 3 — Ventana de tiempo
Pregunta: ¿de todos los tiempos, o un rango de fechas? Y para el resumen de consola, agrupa por mes / trimestre / año? El informe HTML siempre contiene todo el historial con un filtro de tiempo en vivo; la ventana principalmente da forma a la tabla de clasificación de consola que narras.
Mapa → rank [DESDE HASTA [month|quarter|year]].
Paso 4 — Filtros de ruido
Explica los valores predeterminados y permite ajustarlos:
- Bots (
dependabot, CI, agentes de IA) — excluidos por defecto (DROP_BOTS=1). - Volcados masivos/vendedores (importaciones de framework, código generado) — cualquier commit único que supere
MAXCHURN=10000líneas oMAXFILES=400archivos se descarta para que no pueda coronar a un ganador falso. Ofrece "sin procesar, sin filtrado" (MAXCHURN=0 MAXFILES=0 DROP_BOTS=0) si lo desean.
Mapa → variables de entorno DROP_BOTS, MAXCHURN, MAXFILES.
Paso 5 — Salida
Pregunta: ¿dónde debería ir el informe? Por defecto: directorio actual → ./report.html
(un único archivo autónomo; sin servidor, seguro para enviar por email/Slack). Establece GITPODIUM_OUT.
Paso 6 — Confirmar el plan, luego ejecutar
Devuelve un plan de un párrafo: propietarios, métrica, ventana, filtros, salida. Con la aprobación, exporta las variables de entorno elegidas y ejecuta — para muchos repos, ejecuta la clonación en segundo plano:
export GITPODIUM_OUT="<dir-salida>" GITPODIUM_METRIC="<métrica>" \
MAXCHURN=<n> MAXFILES=<n> DROP_BOTS=<0|1>
"$GP/bin/clone-all.sh" <propietarios...> # o: -f repos.txt (idempotente; re-ejecutar actualiza)
"$GP/bin/build-mailmap.py" "$GITPODIUM_OUT/clones"
"$GP/bin/collect.sh" "$GITPODIUM_OUT/clones"
"$GP/bin/rollup.sh"
"$GP/bin/collect-github.py" <propietarios...> # PRs/revisiones/issues -> github.json (API gh; omitir con GITPODIUM_SKIP_GITHUB=1)
"$GP/bin/build-report.py" # -> $GITPODIUM_OUT/report.html (incluye ambos conjuntos de datos)
(Equivalente de un solo comando: "$GP/gitpodium" run <propietarios...> después de exportar las variables de entorno —
run incluye el paso de GitHub con el mejor esfuerzo, por lo que el informe de git aún se construye si la API falla.)
Paso 7 — Revisar identidades (ofrecer, no forzar)
Después de build-mailmap.py, imprime cuántas identidades se fusionaron y escribe
mailmap-review.md — sugerencias de baja confianza (un nombre es prefijo de otro) que se
dejaron sin fusionar. Ofrece mostrarlo. Si el usuario confirma alguna fusión, escríbela en un
gitpodium.identity.json (force_merge / canonical_override / extra_bots — ver
examples/gitpodium.identity.json), establece GITPODIUM_IDENTITY a él, y vuelve a ejecutar
build-mailmap.py → collect.sh → rollup.sh → build-report.py.
Paso 8 — Entregar
- Señala al usuario el
report.html(lo abren en cualquier navegador). - Narra los principales contribuidores con
"$GP/bin/report.sh"(respeta la misma ventana/filtro de entorno). La línea de transparencia muestra cuántos commits/churn se descartaron como bulk/bots — menciónalo para que nada parezca oculto. - Señala la pestaña de Colaboración (si
github.jsonse construyó): los principales revisores y el conteo de "revisores invisibles para el churn" — personas que revisan mucho pero abren pocos PRs, a quienes la tabla de clasificación de git pasa por alto por completo. Este es el titular para mirar más allá del churn. - SIEMPRE cierra con la advertencia (no negociable):
Churn ≠ contribución. La revisión de código, mentoría, diseño y depuración son invisibles para git; las ramas fusionadas con squash/eliminadas son irrecuperables. La pestaña de Colaboración recupera algo de eso (revisiones, PRs, issues) pero no todo. Esto es un iniciador de conversación, no un ranking jerárquico o una métrica de rendimiento.
Referencia rápida (respuesta de entrevista ↔ configuración)
| Respuesta de entrevista | Configuración |
|---|---|
| Propietarios / repos | clone-all.sh <propietario...> o -f repos.txt |
| Métrica (vista de churn git) | `GITPODIUM_METRIC=churn |
| Colaboración (PRs/revisiones/issues) | collect-github.py <propietario...> → github.json · omitir: GITPODIUM_SKIP_GITHUB=1 |
| Ventana / agrupación | `report.sh DESDE HASTA [month |
| Filtros de bots / bulk | DROP_BOTS MAXCHURN MAXFILES |
| Fusiones de identidad | GITPODIUM_IDENTITY=gitpodium.identity.json |
| Directorio de salida | GITPODIUM_OUT (directorio de clones: GITPODIUM_CLONES) |