Arch Discover

Skill: Descubrir arquitectura en un proyecto existente

Analiza la estructura y el código de un repositorio para identificar arquitectura implícita — elecciones de tecnología, patrones, convenciones o compromisos que están vivos en el código pero nunca se documentaron formalmente.

Cada hallazgo se traduce en artefactos de dos tipos (ver el skill arch-manage para la distinción completa):

• Un ADR — la decisión histórica: por qué se eligió algo. Todo hallazgo relevante produce un ADR candidato.
• Un requisito dentro de un estándar de dominio — la regla viva que el código sigue hoy (docs/standards/). El estándar es amplio (un dominio técnico o funcional entero: Testing Standards, API Standards…; un aspecto de arquitectura, no un dominio de negocio/DDD) y agrupa varios requisitos; cada requisito se redacta con RFC 2119/8174 (MUST/SHOULD/MAY…). Un hallazgo que es una norma continua y verificable propone un requisito, dentro del estándar de dominio que le corresponde (agrupándolo con otros del mismo dominio). La unidad verificable fina —el criterio de cumplimiento (CR-XXX), que pertenece a un requisito pero vive en la tabla única del estándar— la propone arch-manage al crear el artefacto, para que el usuario elija cuáles crear; en descubrimiento basta con proponer el requisito y su regla.

Ejemplo: detectar "unit tests con PHPUnit" y "e2e con Playwright" son dos decisiones (dos ADR), pero un solo estándar de dominio Testing Standards con dos requisitos («Unit testing», «E2E testing»). En cambio detectar "hubo una migración de Webpack a Vite" es una decisión histórica (ADR sin criterio de cumplimiento): no hay una norma continua que cumplir, solo un hecho.

El output es una lista priorizada de candidatos, agrupando los requisitos por estándar de dominio. El usuario decide cuáles documentar; el skill luego invoca arch-manage para cada uno aprobado, que crea el ADR y —cuando aplique— añade su requisito al estándar de dominio (creándolo o ampliándolo). Este skill es autocontenido: cuando se invoca (directamente o como subagente desde otro skill, p. ej. arch-init), corre sus cinco fases hasta el final, incluida la creación de los artefactos aprobados — nadie más los vuelve a crear después.

Rutas de las referencias compartidas

${PLUGIN_ROOT} es la raíz del plugin instalado (la carpeta que contiene skills/, agents/ y reference/), y toda referencia compartida de este skill se escribe como ${PLUGIN_ROOT}/reference/<archivo>.md. Resolverla así, en este orden: (1) en Claude Code, ${PLUGIN_ROOT} es ${CLAUDE_PLUGIN_ROOT} — comprobar con echo "$CLAUDE_PLUGIN_ROOT" y usar ese valor; (2) en cualquier otro cliente, o si la variable está vacía, la carpeta desde la que se cargó este archivo, dos niveles arriba. El destino de cada enlace markdown (../../reference/…) existe solo para navegar el repositorio en GitHub o en un editor: no resolverlo desde el directorio de trabajo. Nunca buscar reference/ en el proyecto: un <proyecto>/reference/language.md que no existe no es un archivo que falte, es una ruta mal resuelta — corregir la raíz y volver a leer, sin preguntar al usuario ni saltarse la lectura.

Resolución de idioma

Antes de ejecutar este skill, DEBES leer ${PLUGIN_ROOT}/reference/language.md.

Las reglas de language.md son obligatorias y tienen prioridad para determinar el idioma de todos los artefactos y mensajes generados por este skill.

No continúes hasta haber leído y aplicado language.md.

Fase 1 — Orientación inicial

Antes de inspeccionar, determinar el alcance:

1. Resolver la raíz de arquitectura (<raíz-arq>) — el repositorio cuyo código se va a descubrir y donde vivirán los artefactos resultantes. Listar los repositorios anidados (git submodule status / .gitmodules, más directorios con .git propio): si no hay ninguno, es la raíz del repo actual y no se pregunta; si los hay, preguntar al usuario qué raíz descubrir (principal o submódulo X). Se resuelve una vez para todo el lote y todo lo demás —inspección, lectura de artefactos existentes y creación— es relativo a ella. Regla completa: ${PLUGIN_ROOT}/reference/artifacts.md.
2. Leer AGENTS.md (si existe, sección # Stack tecnológico) y .agents/MEMORY.md (si existe, contexto operativo) del repo principal para entender lo ya conocido — el harness es uno solo; el stack vive en AGENTS.md y no se duplica en MEMORY.md. Si la raíz elegida es un submódulo, su stack puede diferir del que describe AGENTS.md: prevalece lo que se observe en la Fase 2.
3. Leer docs/adr/ y docs/standards/ de <raíz-arq> para listar los artefactos ya existentes — nunca proponer un candidato que duplique un ADR o estándar existente de esa raíz (en cualquier estado). Los de otra raíz son series independientes y no cuentan como duplicado.
4. Si el usuario no indicó ruta y no hay repositorios anidados, asumir raíz del repositorio actual.

Fase 2 — Inspección del proyecto

Explorar en este orden, acumulando señales:

2a. Estructura de carpetas

find . -maxdepth 3 -type d | grep -v node_modules | grep -v .git | grep -v __pycache__

Inferir: monorepo vs monolito, separación por capas/dominios, presencia de módulos, microservicios, etc.

2b. Manifiestos de dependencias

Leer todos los que apliquen según el stack detectado:

Señales clave a extraer:

• Framework web principal (Express, FastAPI, Spring, etc.)
• ORM / cliente de base de datos
• Bus de mensajes / queue
• Herramientas de test
• Bundler / transpilador
• Librerías de autenticación / autorización
• Clientes de servicios cloud

2c. Código fuente — patrones arquitectónicos

Buscar evidencia de patrones en el código:

# Detectar estructura de capas
find src -type d | head -30

# Buscar patrones de diseño comunes
grep -r "Repository\|Service\|Controller\|Handler\|UseCase\|Interactor" src --include="*.ts" --include="*.py" --include="*.java" -l 2>/dev/null | head -20

# Detectar uso de inyección de dependencias
grep -r "inject\|Injectable\|@Autowired\|provide\|container" src -l 2>/dev/null | head -10

2d. Artefactos existentes

Desde <raíz-arq> (sustituir por su ruta si no es el directorio actual):

ls docs/adr/*.md docs/standards/*.md 2>/dev/null || echo "No hay ADRs ni estándares"

Para cada uno, leer solo lo clave (## Decisión de los ADR; el title/domain y los requisitos ## <…> de los estándares); no cargar el documento completo si hay muchos.

Fase 3 — Identificación de candidatos

Para cada señal encontrada, evaluar si amerita documentarse usando estos criterios:

Incluir como candidato si:

• Es una elección no obvia entre varias alternativas reales (ej: Redux vs Zustand, REST vs GraphQL)
• Tiene consecuencias que afectan a múltiples partes del sistema
• Sería costoso revertir sin una razón documentada
• Un desarrollador nuevo podría cuestionarla razonablemente

Excluir si:

• Ya está cubierta por un ADR o por un requisito de estándar existente
• Es la opción por defecto obvia del stack (ej: usar Jest en un proyecto CRA)
• Es una decisión de implementación, no arquitectónica

Clasificar cada candidato: ¿fija un requisito? ¿de qué dominio técnico/funcional?

Por cada candidato, además de la decisión (ADR), determinar si hay una regla viva que documentar como requisito dentro de un estándar de dominio:

• Decisión + requisito — el código sigue hoy una norma continua y verificable (p. ej. "las APIs son GraphQL", "el dominio no importa infraestructura", "unit tests con PHPUnit"). Proponer el ADR y el requisito, indicando a qué estándar de dominio pertenece (agrupándolo con otros candidatos del mismo dominio bajo un solo estándar).
• Solo decisión (ADR) — una elección histórica o puntual sin una regla continua que cumplir (una migración ya ejecutada, la adopción inicial de un runtime). Proponer solo el ADR.

Agrupar por dominio: varios candidatos del mismo dominio se consolidan en un estándar. P. ej. "unit tests con PHPUnit" + "e2e con Playwright" + "cobertura ≥ 80%" → un estándar Testing Standards con tres requisitos.

Categorías / dominios típicos a buscar

Leer references/functional-domains.md para el catálogo completo de los nueve dominios funcionales canónicos (los mismos que usa arch-manage) y clasificar cada candidato en uno de ellos — proponer un dominio nuevo solo si de verdad no encaja en ninguno.

Fase 4 — Presentación de candidatos

Leer references/candidate-presentation.md para el formato exacto (con ejemplo) en el que se muestra la lista al usuario, agrupada por prioridad (🔴 alta / 🟡 media / ⚪ baja) e indicando a qué estándar de dominio aportaría cada requisito. Al final de la lista, preguntar con la herramienta de preguntas estructuradas cuáles documentar (esa referencia trae la pregunta exacta y sus opciones).

Fase 5 — Creación de los artefactos aprobados

Por cada candidato aprobado por el usuario:

1. Invocar el skill arch-manage pasando como contexto:

   • El título sugerido de la decisión
   • La evidencia encontrada (como contexto para el ## Contexto del ADR)
   • La decisión inferida
   • Si fija un requisito: el enunciado de la regla en lenguaje RFC 2119 y el estándar de dominio al que pertenece (para que arch-manage cree o amplíe ese estándar)
   • Las alternativas implícitas detectadas (si las hay)
   • Los Decisores, acordados una sola vez para todo el lote, de modo que arch-manage no vuelva a preguntar lo mismo por cada artefacto
   • La raíz de arquitectura (<raíz-arq>) resuelta en la Fase 1, para que arch-manage escriba ahí y no vuelva a preguntarla por cada artefacto del lote

2. Dejar que arch-manage ejecute su flujo completo: crea el ADR y, cuando corresponda, añade el requisito al estándar de dominio (creándolo o ampliándolo), propone los criterios de cumplimiento candidatos con su mecanismo de verificación para que el usuario elija cuáles crear, escribe los seleccionados como CR-XXX con su Enfoque (bloqueante/warning), enlaza emits (a nivel de CR) / source_adrs y crea las fitness functions elegidas. En lote, esa propuesta y selección se presenta una sola vez para todos los candidatos aprobados (una tabla con columna Estándar), no una por artefacto.

3. Agrupar por dominio en el lote: procesar juntos los candidatos del mismo dominio para que sus requisitos caigan en el mismo estándar (no crear un estándar por candidato).

   Propuesta de criterios, una sola vez para el lote. Los ADR y los bloques de requisito se crean candidato a candidato, pero la propuesta y selección de los criterios de cumplimiento (con su mecanismo de verificación) se acumula y se presenta al final del lote, en una sola tabla con columna Estándar, con una única tanda de preguntas. No lanzar la selección por cada candidato.

4. Una vez creado cada artefacto, continuar con el siguiente candidato aprobado.

Este skill no deja candidatos "aceptados pero pendientes de crear": todo lo que el usuario aprueba en la Fase 4 queda creado al final de la Fase 5, en la misma ejecución. Un skill que invoque arch-discover como subagente (p. ej. arch-init) debe dejarlo correr hasta aquí — no hay un modo que se detenga antes.

Notas de comportamiento

• No narrar el flujo interno. Nada de anunciar que se resuelve el idioma o la política, que se lee settings.json, que se carga una referencia, ni ir enumerando las fases en voz alta. Al usuario se le comunica el resultado, las preguntas que el flujo exija y lo que quede pendiente — no la maquinaria.
• No inventar decisiones ni reglas. Si la evidencia es ambigua, mencionar la incertidumbre en "Evidencia" y marcarlo como baja prioridad.
• No proponer artefactos triviales. "Usamos Git" no es un ADR.
• No repetir trabajo. Si ya existe un ADR o un requisito de estándar que cubre el hallazgo, omitir el candidato y mencionarlo en un pie de página: "X hallazgos omitidos por estar ya documentados."
• Distinguir decisión de regla, y agrupar por dominio. No todo ADR fija un requisito; proponer requisito solo cuando hay una norma continua y verificable. Consolidar los requisitos del mismo dominio en un solo estándar (no un estándar por regla).
• Priorizar calidad sobre cantidad. Mejor 4 candidatos sólidos que 12 rellenos.
• Una raíz por corrida. El descubrimiento cubre una raíz de arquitectura: no mezclar hallazgos del repo principal y de un submódulo en el mismo lote, ni escribir sus artefactos en la raíz equivocada. Para cubrir otra raíz, otra corrida.

Archivos del skill (contexto progresivo)

Este SKILL.md contiene el flujo completo de las cinco fases. El catálogo de dominios y el formato de presentación están en references/; leerlos solo cuando la fase correspondiente lo pida:

• references/functional-domains.md — catálogo de los 9 dominios funcionales canónicos. Leer en la Fase 3, al clasificar el dominio de cada candidato.
• references/candidate-presentation.md — formato y ejemplo completo para presentar la lista de candidatos al usuario. Leer en la Fase 4.

Referencias compartidas del plugin

Reglas transversales del catálogo; viven en la raíz del plugin, no en este skill.

• ${PLUGIN_ROOT}/reference/language.md: Idioma — resolución obligatoria del idioma de artefactos y mensajes. Lectura obligatoria antes de ejecutar el skill.