# Arch Discover

> Inspeccionar un proyecto existente para descubrir decisiones arquitectónicas implícitas y las reglas/convenciones vivas que están en vigor, y proponer los ADR y estándares candidatos que las documentarían. Usar cuando el usuario quiera auditar un repositorio en busca de decisiones o normas no documentadas, pida "descubrir ADRs", "descubrir estándares", "qué decisiones arquitectónicas tiene este proyecto", "qué convenciones sigue el código", "analiza la arquitectura del proyecto" o cualquier variante que implique explorar el código/estructura para inferir arquitectura relevante que merezca documentarse. Activar también cuando el usuario llegue a un proyecto nuevo y quiera entender qué decisiones y reglas ya existen, aunque no mencione explícitamente "ADR" o "estándar". Descubre una raíz de arquitectura por corrida —el repo principal o un submódulo—, y crea los artefactos aprobados en esa misma raíz.

- Skill: `juanca202/arch-discover` (Agent Skill, multi-file: 3 files)
- Install (CLI): `npx skillmds@latest add juanca202/arch-discover`
- Raw SKILL.md: https://api.skillmd.com/api/skills/juanca202/arch-discover/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- License: MIT
- Author: juanca202 (https://skillmd.com/u/juanca202)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/juanca202/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`](../../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`](../../reference/artifacts.md#raíz-de-arquitectura-adr-estándares-y-fitness-functions).
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
```bash
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:

| Ecosistema | Archivos a leer |
|---|---|
| Node / JS / TS | `package.json`, `package-lock.json`, `tsconfig.json` |
| Python | `pyproject.toml`, `requirements.txt`, `setup.cfg`, `Pipfile` |
| JVM | `pom.xml`, `build.gradle`, `build.gradle.kts` |
| .NET | `*.csproj`, `*.sln` |
| Rust | `Cargo.toml` |
| Go | `go.mod` |

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:

```bash
# 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):

```bash
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`](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`](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`](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`](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`](../../reference/language.md): **Idioma** — resolución obligatoria del idioma de artefactos y mensajes. *Lectura obligatoria antes de ejecutar el skill.*