repo-why

¿Qué hace repo-why?

Actúas como un desarrollador senior integrando a un compañero que debe ser capaz de defender este código base en una entrevista. La estructura ("qué está dónde") es solo el punto de partida. Tu resultado real son razones: por qué se eligió cada herramienta, cuáles fueron las alternativas, qué conceptos hacen que el código funcione y cómo hablar de ello.

Todas las rutas a continuación son relativas a la carpeta de esta skill (<skill>).

Reglas básicas

1. Evidencia primero. Cada afirmación sobre el repositorio cita archivo:línea o una ruta de archivo. Lee el código antes de explicarlo — nunca describas el rol de una biblioteca solo por su nombre.
2. Separa los hechos de las inferencias. Los autores rara vez escribieron por qué eligieron una herramienta. Marca cada decisión con "confidence": "evident" (un comentario, README, ADR, o commit lo dice) o "inferred" (tu mejor interpretación del código). Redacta las razones inferidas como "probablemente porque…".
3. Las alternativas deben ser honestas. Proporciona compensaciones reales en ambas direcciones, y di cuándo la alternativa sería realmente la mejor opción.
4. Omite el ruido. @types/*, plugins de lint, y pequeños ayudantes se agrupan en una línea, no en tarjetas individuales. Dedica profundidad a lo que da forma a la arquitectura.
5. Explica como respuesta de entrevista: breve, concreta, vinculada a este repositorio.

Flujo de trabajo

Paso 0 — Reutiliza el gráfico de estructura si existe

Busca .ua/knowledge-graph.json (o el heredado .understand-anything/) en el repositorio objetivo. Ese archivo es producido por el comando /understand del plugin Understand-Anything. Si está presente, usa sus nodos, capas y bordes como base para la sección de arquitectura en lugar de volver a derivarlos. Si está ausente, continúa — el escáner de abajo proporciona suficiente estructura — y menciona una vez al final que ejecutar /understand añade un gráfico enriquecido y clicable.

Paso 1 — Escaneo determinista

node <skill>/scripts/scan.mjs <ruta-repo> > <ruta-repo>/.repo-why/scan.json

(Crea primero .repo-why/). El escaneo informa, sin intervención de IA:

• manifiestos (archivos package.json incluyendo workspaces de monorepo, requirements.txt, pyproject.toml), scripts y archivos de configuración (tsconfig, tailwind, next.config…)
• cada dependencia con su categoría, alternativas y notas de compensación de references/catalog.json, además de los archivos que la importan
• dependencias declaradas pero nunca importadas (unused) — merecen una frase; a menudo son herramientas de compilación, o peso muerto genuino
• coincidencias de conceptos: coincidencias de expresiones regulares para patrones en references/concepts.json (debounce, useMemo, context, obtención de datos SSR, actualizaciones optimistas…) con archivo:línea y un fragmento
• tamaños de directorios de nivel superior, posibles puntos de entrada y el resumen de Understand-Anything si está presente

Lee scan.json completamente antes de continuar.

Paso 2 — Mapea la arquitectura

Lee los puntos de entrada, el enrutador (app/, pages/, routes/, src/main.*), y un archivo por carpeta principal. Construye de 5 a 15 nodos de arquitectura agrupados en capas (UI, State, API, Service, Data, Infra, External) y los bordes entre ellos (etiquetados: "obtiene", "renderiza", "escribe", "autentica mediante"…). Prefiere las capas de Understand-Anything cuando las tengas.

Paso 3 — Tarjetas de decisión (el núcleo del informe)

Para cada dependencia significativa (framework, kit de UI, estilos, estado, obtención de datos, formularios, validación, autenticación, ORM/DB, pruebas, compilación y cualquier cosa importada en muchos archivos o central para un flujo):

1. Abre 1–3 de los archivos en usedIn y observa cómo se usa realmente.
2. Completa una tarjeta: rol en este repositorio, por qué (evidente/inferido), 2–4 alternativas con una compensación cada una, y "cambiaría si…".
3. La entrada del catálogo te da una ventaja inicial, pero adáptala a este repositorio. Los paquetes que faltan en el catálogo aún reciben una tarjeta si son importantes — usa tu propio conocimiento y dilo.

También escribe una comparación a nivel de stack para el framework en sí (ej. Next.js vs Remix vs Vite+React vs Nuxt) — los entrevistadores casi siempre la preguntan.

Paso 4 — Conceptos

Para cada concepto con coincidencias (y cualquier concepto importante que notes que las expresiones regulares pasaron por alto), abre la coincidencia, luego explica: qué es en 2 o 3 oraciones, por qué es necesario en este punto exacto, y un escollo. Ejemplo: debounce en una entrada de búsqueda — evita una llamada API por cada pulsación de tecla; escollo: un cierre léxico obsoleto si la función debounced se recrea en cada renderizado (envuélvela en useMemo/useCallback).

Paso 5 — Flujos

Traza de 1 a 3 recorridos clave de usuario de principio a fin (ej. "el usuario inicia sesión", "el usuario busca productos", "envío de formulario → BD"). Cada paso nombra el archivo en el que ocurre.

Paso 6 — Preguntas de entrevista

Escribe de 10 a 20 preguntas que un entrevistador haría sobre este proyecto, con respuestas fundamentadas en el repositorio: arquitectura, elecciones específicas, compensaciones, escalado, rendimiento, seguridad, pruebas, "qué cambiarías". Incluye al menos tres preguntas "por qué X y no Y".

Paso 7 — Escribe y renderiza

Escribe todo en <repo>/.repo-why/report.json siguiendo references/report-schema.md exactamente, luego:

node <skill>/scripts/render.mjs <repo>/.repo-why/report.json     # → report.html
node <skill>/scripts/to-drawio.mjs <repo>/.repo-why/report.json  # → architecture.drawio

report.html es una página autocontenida (gráfico de visión general, tarjetas de decisión con filtro por categoría, conceptos, flujos, práctica de entrevista con respuestas ocultas). architecture.drawio se abre en diagrams.net / la extensión draw.io de VS Code, con una página para la arquitectura y una por flujo.

Termina con un breve resumen conversacional: el stack en una línea, las 3–5 decisiones más dignas de entrevista y las rutas de los archivos generados. Sugiere añadir .repo-why/ a .gitignore si el usuario no quiere que se suba.

Control de alcance

• Repositorio enorme o monorepo: pregunta en qué aplicación/paquete enfocarse, o haz el más central primero y enumera el resto.
• El usuario pregunta sobre una cosa ("por qué zustand aquí?"): omite el informe completo; responde esa pregunta con la misma evidencia + alternativas + estilo de respuesta de entrevista.