Skill: Descubrir ADRs en un proyecto existente

adr-manage

Fase 1 — Orientación inicial

1. Leer

   .agents/MEMORY.md

   (si existe) para entender el stack y contexto ya conocido.
2. Leer

   docs/adr/

   para listar los ADRs ya existentes — nunca proponer un candidato que duplique uno existente (

   Accepted

   ,

   Proposed

   o

   Draft

   ).
3. Si el usuario no indicó ruta, asumir raíz del repositorio actual.

Fase 2 — Inspección del proyecto

2a. Estructura de carpetas

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

2b. Manifiestos de dependencias

package.json

package-lock.json

tsconfig.json

pyproject.toml

requirements.txt

setup.cfg

Pipfile

pom.xml

build.gradle

build.gradle.kts

*.csproj

*.sln

Cargo.toml

go.mod

• 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

# 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. ADRs existentes

ls docs/adr/*.md 2>/dev/null || echo "No hay ADRs"

## Decisión

Fase 3 — Identificación de candidatos

• 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

• Ya está cubierta por un ADR 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

Categorías típicas a buscar

Fase 4 — Presentación de candidatos

## ADRs Candidatos Descubiertos

### 🟢 Alta prioridad (decisiones con amplio impacto)

**[C-01] Uso de TypeScript en modo strict**
- Evidencia: `tsconfig.json` con `"strict": true`
- Por qué es una decisión: afecta toda la experiencia de desarrollo y la curva de onboarding
- ADR existente: ninguno

**[C-02] Arquitectura en capas (Controller → Service → Repository)**
- Evidencia: estructura de carpetas `src/controllers/`, `src/services/`, `src/repositories/`
- Por qué es una decisión: define los límites de responsabilidad en todo el sistema
- ADR existente: ninguno

### 🟡 Media prioridad (decisiones relevantes, alcance acotado)

**[C-03] Uso de Prisma como ORM**
- Evidencia: `@prisma/client` en `package.json`, carpeta `prisma/`
- Por qué es una decisión: alternativa a TypeORM, Drizzle, Sequelize — no es la única opción
- ADR existente: ninguno

### ⚪ Baja prioridad (convenciones, menor impacto)

**[C-04] ESLint + Prettier para linting y formato**
- Evidencia: `.eslintrc.js`, `.prettierrc`
- Por qué es una decisión: establece el estándar de calidad de código del equipo
- ADR existente: ninguno

---
Total: X candidatos encontrados. ¿Cuáles quieres documentar como ADR?

"¿Cuáles candidatos quieres crear como ADR? Puedes indicarlos por código (C-01, C-03…), por rango (C-01 a C-04), o decir 'todos los de alta prioridad'."

Fase 5 — Creación de ADRs aprobados

1. Invocar el skill

   adr-manage

   pasando como contexto:
   • El título sugerido
   • La evidencia encontrada (como contexto para la sección

     ## Contexto

     )
   • La decisión inferida
   • Las alternativas implícitas detectadas (si las hay)
2. Dejar que

   adr-manage

   ejecute su flujo completo (incluyendo preguntar decisores, estado, etc.).
3. Una vez creado cada ADR, continuar con el siguiente candidato aprobado.

Notas de comportamiento

• No inventar decisiones. Si la evidencia es ambigua, mencionar la incertidumbre en la columna "Evidencia" y marcarlo como baja prioridad.
• No proponer ADRs triviales. "Usamos Git" no es un ADR.
• No repetir trabajo. Si ya existe un ADR que cubre la decisión, omitir el candidato y mencionarlo en un pie de página: "X decisiones omitidas por estar ya documentadas."
• Priorizar calidad sobre cantidad. Mejor 4 candidatos sólidos que 12 rellenos.
• Idioma: seguir la convención de

  .agents/MEMORY.md

  ; si no existe, usar el idioma del mensaje del usuario.