AppleDev879/ramp-claude-skill

ramp

Convierte un tema en un repositorio desconocido en un mapa interactivo: nodos agrupados, aristas etiquetadas, un panel de detalles con clic y un recorrido numerado que traza la secuencia real de ejecución.

El pipeline está deliberadamente dividido. Una pasada estática encuentra qué código importa, tú decides qué significa y un renderizador lo dibuja. Saltarse la pasada estática y leer el repositorio sin guía es más lento y omite archivos; saltarse tu pasada produce un grafo de llamadas del que nadie aprende nada.

Flujo de trabajo

1. Escanear

node ~/.claude/skills/ramp/scripts/scan.js <repositorio> --topic "<tema>" --max 30 --out /tmp/scan.json

Las rutas son absolutas porque ejecutarás desde el repositorio de destino, no desde aquí.

Ejecútalo sin --topic primero si aún no conoces la forma del repositorio; esto imprime una visión general con la mezcla de lenguajes, los directorios más grandes y los archivos más importados (hubs), que suele ser suficiente para elegir un buen tema.

El escaneo de tema devuelve nodes clasificados (archivos, con score, términos matched y defs extraídas) más edges entre ellos. seed: true marca una coincidencia directa con el tema; el resto llegó por expansión del grafo y son los llamadores y llamados que completan la imagen.

Si no devuelve nada, los términos del tema no aparecen en el código. Prueba el vocabulario que usa el código base en lugar del vocabulario que usó el usuario.

2. Leer

Lee los archivos semilla y cualquier nodo expandido con un nombre sugerente. Léelos adecuadamente: todo el valor del mapa está en la explicación, y no puedes escribir un detail útil a partir de un listado de archivos.

Mientras lees, busca específicamente:

• el punto de entrada — ¿dónde comienza este flujo en tiempo de ejecución?
• lo no obvio — la guarda que previene un error, la bandera de configuración que hace el trabajo real, lo que sorprendería a un recién llegado
• la secuencia real — qué llama a qué, en qué orden, en tiempo de ejecución

3. Modelar

Escribe un JSON del modelo (esquema abajo). Esta es la parte que requiere criterio.

4. Renderizar

node ~/.claude/skills/ramp/scripts/render.js /tmp/model.json -o /tmp/<repositorio>-<tema>.html

Valida estrictamente y se niega a renderizar un modelo roto: IDs de nodo desconocidos en aristas, IDs duplicados, referencias de recorrido colgantes. Las advertencias sobre nodos inexplicados o huérfanos vale la pena arreglarlas en lugar de ignorarlas.

5. Publicar

Publica el archivo renderizado con la herramienta Artifact y dale al usuario el enlace. No cargues artifact-design primero — la plantilla ya está diseñada; publícala tal cual.

Esquema del modelo

{
  "title": "Flujo de inicio de sesión",
  "repo": "mi-app",
  "summary": "Una o dos frases: la forma de la cosa, y el hecho más útil sobre ella.",
  "groups": [{ "id": "boot", "label": "Arranque de la app", "hint": "tooltip opcional" }],
  "nodes": [{
    "id": "provider",
    "label": "AuthProvider",
    "group": "provider",
    "role": "Gestiona el estado de sesión",
    "detail": "El párrafo que un recién llegado realmente necesita.",
    "files": ["src/context/AuthContext.jsx:12"],
    "symbols": ["AuthProvider", "signInWithGoogle"]
  }],
  "edges": [{ "from": "provider", "to": "supabase", "label": "getSession, OAuth" }],
  "walkthrough": [{ "node": "provider", "text": "Lo que ocurre en este paso." }]
}

Los groups son columnas, de izquierda a derecha, en orden de dependencia — puntos de entrada a la izquierda, primitivas a la derecha. Las aristas se dibujan desde el importador hacia lo importado, por lo que un modelo cuyos grupos sigan ese orden se distribuye limpiamente. Hasta seis grupos obtienen colores distintos.

walkthrough es opcional, pero es la característica que enseña. Ordénalo por secuencia de ejecución, no por estructura de archivos. Un nodo puede aparecer más de una vez — los flujos retroceden, y mostrar eso es el objetivo.

Qué diferencia un mapa bueno de uno inútil

Los nodos son conceptos, no archivos. Dos archivos que son una idea (AuthContext.jsx + AuthContextValue.js) pueden ser un solo nodo; un archivo que alberga dos responsabilidades no relacionadas puede ser dos. Pon cada archivo real en files independientemente.

6–14 nodos. Un mapa con 40 nodos es la madeja que el usuario ya estaba mirando. Reduce a lo que lleva el flujo: el ordenamiento por score del escaneo te dice qué conservar. Di lo que omitiste en el summary.

role es un trabajo, no una repetición. "Gestiona el estado de sesión" — no "Componente proveedor de autenticación".

detail se gana el clic. Pon lo que no es obvio a partir del nombre: por qué está dividido de esta manera, la bandera que importa, el fallo que previene, la suposición que hace. Si un detail solo parafrasea la etiqueta, elimina el nodo o descubre qué hace realmente.

Etiqueta cada arista con la relación real — "depende de usuario", "getSession, OAuth" — no "usa" o "importa".

Cita líneas. ruta/al/archivo.ts:42 en files dirige al lector al punto exacto.

Di qué es crítico y qué no. Un recién llegado necesita saber sobre todo qué partes puede ignorar.

Notas

• El escaneo es Node sin dependencias y no necesita instalación. Respeta .gitignore cuando el destino es un repositorio git.
• Swift, y Java/C# del mismo paquete, no tienen importaciones a nivel de archivo; para esos, el escaneo infiere aristas a partir de referencias de tipo únicas. Trata esas aristas como indicios sólidos más que certezas.
• La resolución de importaciones se basa en expresiones regulares, no en un verificador de tipos. Resuelve rutas relativas, alias del empaquetador (@/) y especificadores de estilo paquete por sufijo de ruta. Las importaciones dinámicas y generadas se pasan por alto — si esperas un archivo y no aparece, agrégalo tú mismo al modelo.