dji-sq/DSH-skill

Extracción de GitHub

El problema que resuelve esta habilidad

Un usuario envía un enlace de GitHub, pero normalmente no quiere un montón de contenido de archivos, sino entender tres cosas:

1. ¿De qué trata este proyecto?
2. ¿Qué problema busca resolver este cambio?
3. ¿Por qué se eligió este enfoque?

Los archivos, diffs y metadatos son solo evidencia. Entregar la evidencia como si fuera la conclusión equivale a no haber extraído nada: el lector obtiene un montón de tablas, pero no puede explicar la razón de ser del repositorio.

Criterio de finalización (en una frase): Una persona que nunca haya oído hablar de este repositorio, después de leer las primeras 300 palabras, debe poder parafrasear con sus propias palabras "qué problema resuelve, qué cambió y por qué lo cambió así". Si no se logra, la extracción no ha terminado.

Paso 0: Lee el "proyecto" primero, luego la "página"

Antes de capturar un PR o issue, primero entiende el contenedor. Saltarse este paso hace que todo lo que se escriba después quede sin contexto.

Pregunta a responder	Dónde leer
¿Qué es este proyecto?	description del repo, topics, inicio del README
¿Qué vacío llena / qué reemplaza?	La columna "Por qué" de cada paquete en el README
¿Quién lo usa y en qué contexto?	Instalación / Uso / Desarrollo del README
¿Dónde se sitúa este cambio?	La rama base del PR, el rol del paquete modificado en el inventario

Los monorepos / colecciones de plugins son especialmente delicados: Primero debes listar la correspondencia "nombre del paquete → responsabilidad en una frase"; de lo contrario, el lector no podrá ubicar el cambio. Si el README usa mucha jerga técnica (como "lifecycle hooks", "ctx.web seam"), tradúcela primero a lenguaje sencillo antes de entrar al cuerpo del texto.

Paso 1: Identifica el tipo de URL

Forma de la URL	Tipo	Fuente de datos principal
github.com/{o}/{r}	repo	/readme + git/trees?recursive=1
…/issues/{n}	issue	issues/{n}
…/pull/{n}	PR	pulls/{n} + pulls/{n}/files + pull/{n}.diff
…/commit/{sha}	commit	commits/{sha}
…/blob/{ref}/{path}	archivo	contents/{path}?ref={ref} (base64)

#1 es un fragmento, no una ruta. Los issues y los PRs comparten un espacio de numeración: si /issues/1 redirige (302) a /pull/1, entonces es un PR y debes decirlo explícitamente.

Paso 2: Obtén el texto completo desde la API, no luches contra el HTML

• El HTML de la página solo proporciona la barra de navegación y el cuerpo truncado; el texto completo siempre debe obtenerse desde api.github.com.
• El parche se obtiene de patch-diff.githubusercontent.com/raw/{o}/{r}/pull/{n}.diff (github.com/.../pull/n.diff redirige a otro dominio, debes conectar directamente a la URL final).
• raw.githubusercontent.com suele no estar disponible; usa la decodificación base64 de contents en su lugar.
• Si el git o curl local reporta un error TLS SEC_E_NO_CREDENTIALS, no intentes reparar el shell, usa web_fetch del harness; no trates un "fallo de clonación" como un obstáculo para la tarea.

Paso 3: Validación cruzada

additions/deletions/changed_files ↔ lista de files ↔ hunk del .diff; el SHA de la cabeza del PR ↔ la ref del parche; merged no puede determinarse solo por state=closed. Si hay inconsistencias, sigue investigando (probablemente sea por paginación o un parche antiguo), no redactes un producto contradictorio.

Paso 4: Organiza en un producto "legible"

El orden es obligatorio: explicación primero, evidencia después. El lector no debería tener que pasar 200 líneas de tablas para entender de qué se trata.

1. Qué es (150–300 palabras, en lenguaje sencillo) — La razón de ser del proyecto, qué vacío llena. La primera vez que aparezca un término técnico, debes explicarlo en una frase: hookkit = convertir "escribir un plugin para enganchar ciclos de vida" en "escribir un YAML".
2. Qué problema resuelve este cambio — Escríbelo como una comparación "antes era así → ahora es así", no uses una lista de archivos como sustituto.
3. Por qué se eligió este enfoque — Extrae las compensaciones y la cadena causal de la descripción del PR / mensaje de commit (por qué no se usó un trigger push, por qué se trata el registro como estado).
4. Lista de cambios — Tabla: Archivo / Estado / Líneas añadidas-eliminadas / Función en una frase.
5. Texto original — La descripción del PR, el mensaje de commit, citados textualmente, sin reescribir.
6. Contenido completo — El texto completo de cada archivo, sin escribir "... el resto se omite".
7. Prácticas transferibles — Solo deja aquellas que el lector pueda usar realmente la próxima vez.
8. Verificación y cobertura — Ponlo al final como apéndice: resultado de git apply --check, comparación de blob SHA, qué no se capturó.

Reglas de redacción

• Conclusión primero: La primera oración de cada párrafo es la conclusión; luego vienen los fundamentos.
• Las tablas no asumen la responsabilidad de explicar. Todo lo que sea "qué es" o "por qué" debe escribirse en oraciones completas.
• No uses nombres de archivo como sustituto de la descripción de la función: "cambió publish.yml" ❌; "Nuevo flujo de trabajo de publicación manual, solo publica al hacer clic en el botón, por defecto solo ensaya" ✅.
• Los números deben poder rastrearse hasta su origen, pero no pongas los registros de validación al principio.
• Escribe en el mismo idioma que usa el usuario.
• Antipatrones: Grandes acumulaciones de tablas, poner el diff archivo por archivo como cuerpo principal, comenzar con metadatos, términos sin explicar.

Paso 5: Autocomprobación

• Mirando solo las primeras 300 palabras (sin incluir el título de la tabla), ¿se puede responder "qué hace / qué cambió / por qué lo cambió así"? Si no, reescribe.
• ¿Hay algún término que no se haya explicado?
• ¿Se ha usado "los archivos A, B y C tienen cambios" como explicación del cambio?
• ¿git apply --check pasó con el parche? Si no se ejecutó, escríbelo explícitamente como "no verificado".

Modos de fallo

Síntoma	Causa	Manejo
El texto se corta a la mitad	Se capturó HTML	Usar la API
404 en raw.githubusercontent	Lista blanca de red	Decodificar base64 de contents
403 límite de tasa	Ciclo sin autenticación	Procesar por lotes, reducir velocidad, informar las brechas con honestidad
cross-origin redirect not followed	Redirección de .diff	Conectar directamente a patch-diff…
El número de archivos no coincide con changed_files	Paginación	Reobtener con ?per_page=100
El lector comenta "no lo entendí"	Solo se dieron pruebas, sin explicación	Volver al Paso 4, secciones 1–3 y reescribir

Límites

Prioridad: Instrucción explícita del usuario > Restricciones de esta sección > Comportamiento conservador por defecto.

Por defecto, solo extrae contenido, no clones / construyas / instales / ejecutes pruebas. Para repositorios privados, el usuario debe proporcionar un token; no inventes uno. Si el repositorio está archivado, debes indicarlo; el contenido aún se puede extraer, pero el estado afecta la interpretación.

Situaciones en las que debes detenerte y preguntar (no actuar por iniciativa propia)

• El usuario dice "instala esto / ejecuta esto", pero el objetivo es un repositorio de otra persona, o implicaría escribir en el entorno global: primero confirma el alcance y el método de reversión.
• La instrucción es ambigua ("procesa este repositorio"): proporciona una línea de acción predeterminada + una confirmación; no adivines.
• La acción es irreversible o podría modificar el entorno del usuario (pnpm install, paquetes globales, modificar el perfil, crear un PR, hacer push, eliminar archivos): siempre pregunta primero.
• Se requieren credenciales (repositorio privado, token, clave SSH): pregunta una vez; si las obtienes, úsalas; si no, solo genera la parte que se puede verificar públicamente e indica qué falta.

Situaciones en las que puedes ser más flexible

• Es un repositorio del propio usuario y ha dicho explícitamente "siéntete libre de modificarlo / instalar directamente / no preguntes";
• O la acción se realiza dentro de un directorio temporal, sin tocar el repositorio original ni el estado global (en este caso, la flexibilidad solo aplica a "escribir", no a "ejecutar código no confiable").

Al ser flexible, añade una línea al final del producto que diga "Según tu autorización, he ejecutado X", para que los límites superados sean visibles y reversibles.