Nexus - AI Task Orchestrator

07-adr-compliance-check
Procedimiento: ADR Compliance Check

Documentacion
1 plugin(s)
Titulo
Descripcion
Contenido Markdown
8875 caracteres
# Procedimiento: ADR Compliance Check

## Metadata
- **ID**: PROC-07
- **Frecuencia**: Mensual o Post-cambio arquitect├│nico
- **Duraci├│n estimada**: 20-40 min
- **Requiere**: Acceso al repositorio
- **Dependencias**: Ninguna
- **Bloquea**: Ninguno (pero puede bloquear PRs con cambios arquitect├│nicos)
- **Agentes**: documentation-architect, dotnet-architect

---

## Objetivo

Verificar que las decisiones arquitect├│nicas est├ín documentadas:
1. Detectar cambios arquitect├│nicos sin ADR asociado
2. Verificar que ADRs existentes siguen el formato est├índar
3. Identificar ADRs obsoletos o superseded
4. Asegurar trazabilidad decisi├│n ÔåÆ c├│digo

---

## ┬┐Qu├® es un ADR?

**Architecture Decision Record** - Documento corto que captura una decisi├│n arquitect├│nica importante.

**Ubicaci├│n est├índar:** `docs/adr/` o `docs/architecture/decisions/`

**Formato:** `NNNN-titulo-decision.md` (ej: `0001-usar-rabbitmq-para-mensajeria.md`)

---

## Cambios que Requieren ADR

| Tipo de Cambio | Requiere ADR | Ejemplo |
|----------------|--------------|---------|
| Nueva dependencia mayor | S├¡ | A├▒adir RabbitMQ, Redis, Elasticsearch |
| Cambio de framework | S├¡ | Migrar de .NET 6 a .NET 9 |
| Nuevo patr├│n arquitect├│nico | S├¡ | Implementar CQRS, Event Sourcing |
| Cambio de base de datos | S├¡ | Migrar de SQL Server a PostgreSQL |
| Nueva integraci├│n externa | S├¡ | Integrar con Stripe, SendGrid |
| Refactoring menor | No | Renombrar clases, extraer m├®todos |
| Bug fixes | No | Correcci├│n de errores |
| Features simples | No | Nuevo endpoint CRUD |

---

## Checklist Ejecutable

### 1. Verificar Estructura de ADRs

```bash
# Buscar carpeta de ADRs
find . -type d -name "adr" -o -name "decisions" | grep -v node_modules

# Listar ADRs existentes
ls docs/adr/*.md 2>/dev/null || ls docs/architecture/decisions/*.md 2>/dev/null

# Si no existe, crear estructura
mkdir -p docs/adr
```

- [ ] Carpeta docs/adr/ existe
- [ ] ADRs numerados correctamente (0001, 0002, ...)

### 2. Detectar Cambios Arquitect├│nicos Recientes

```bash
# Nuevas dependencias en ├║ltimos 30 d├¡as (.NET)
git log --since="30 days ago" -p -- "*.csproj" | grep -E "PackageReference Include"

# Nuevas dependencias (Node)
git log --since="30 days ago" -p -- "package.json" | grep -E '"dependencies"|"devDependencies"'

# Cambios en configuraci├│n de infraestructura
git log --since="30 days ago" --oneline -- "docker*" "*.yml" "*.yaml" "appsettings*"

# Commits con palabras clave arquitect├│nicas
git log --since="30 days ago" --oneline | grep -iE "architect|migrate|refactor|introduce|replace|implement"
```

- [ ] Nuevas dependencias mayores identificadas
- [ ] Cambios de infraestructura identificados
- [ ] Patrones nuevos identificados

### 3. Cruzar Cambios con ADRs

```bash
# Para cada cambio arquitect├│nico detectado, buscar ADR relacionado
# Ejemplo: si se a├▒adi├│ RabbitMQ
grep -l -i "rabbitmq" docs/adr/*.md

# Si no existe ADR, marcar como faltante
```

**Lista de verificaci├│n:**

| Cambio Detectado | ADR Existe | N├║mero ADR |
|------------------|------------|------------|
| ___ | S├¡/No | ADR-___ |
| ___ | S├¡/No | ADR-___ |

- [ ] Todos los cambios arquitect├│nicos tienen ADR
- [ ] ADRs faltantes identificados

### 4. Validar Formato de ADRs Existentes

**Secciones obligatorias:**

```markdown
# [N├║mero]. [T├¡tulo]

## Status
[Proposed | Accepted | Deprecated | Superseded by ADR-XXX]

## Context
[Descripci├│n del problema o situaci├│n]

## Decision
[La decisi├│n tomada]

## Consequences
[Consecuencias positivas y negativas]
```

```bash
# Verificar que cada ADR tiene las secciones
for adr in docs/adr/*.md; do
  echo "=== $adr ==="
  grep -E "^## (Status|Context|Decision|Consequences)" "$adr"
done
```

- [ ] Todos los ADRs tienen Status
- [ ] Todos los ADRs tienen Context
- [ ] Todos los ADRs tienen Decision
- [ ] Todos los ADRs tienen Consequences

### 5. Identificar ADRs Obsoletos

```bash
# ADRs marcados como Deprecated o Superseded
grep -l -E "Status.*Deprecated|Status.*Superseded" docs/adr/*.md

# ADRs sin actualizaci├│n en >1 a├▒o
find docs/adr -name "*.md" -mtime +365

# Verificar que tecnolog├¡as en ADRs a├║n se usan
# (comparar con dependencias actuales)
```

- [ ] ADRs deprecated identificados
- [ ] ADRs superseded apuntan al nuevo ADR
- [ ] ADRs antiguos revisados

### 6. Verificar Trazabilidad

```bash
# Buscar referencias a ADRs en c├│digo
grep -r "ADR-\|adr-" src --include="*.cs" --include="*.ts" --include="*.js"

# Buscar referencias en PRs (si hay acceso a Git host)
# gh pr list --search "ADR" --state all
```

- [ ] ADRs importantes referenciados en c├│digo
- [ ] PRs de cambios arquitect├│nicos referencian ADRs

---

## Template de ADR

```markdown
# [N├║mero]. [T├¡tulo corto de la decisi├│n]

Date: YYYY-MM-DD

## Status

Accepted

## Context

[Describe el contexto y el problema que requiere una decisi├│n.
┬┐Por qu├® es necesario decidir algo? ┬┐Cu├íles son las fuerzas en juego?]

## Decision

[Describe la decisi├│n tomada y la justificaci├│n.
Usa voz activa: "Usaremos...", "Implementaremos..."]

## Consequences

### Positivas
- [Beneficio 1]
- [Beneficio 2]

### Negativas
- [Trade-off 1]
- [Trade-off 2]

### Neutrales
- [Implicaci├│n que no es ni buena ni mala]

## Alternatives Considered

### [Alternativa 1]
[Por qu├® fue descartada]

### [Alternativa 2]
[Por qu├® fue descartada]

## References

- [Link a documentaci├│n relevante]
- [Link a issue/PR relacionado]
```

---

## Output Esperado

```
====== PROC-07 COMPLETADO [TIMESTAMP] ======
Proyecto: [nombre]

ESTRUCTURA ADR:
- Carpeta: docs/adr/ Ô£à
- ADRs existentes: X

CAMBIOS ARQUITECT├ôNICOS (├║ltimos 30 d├¡as):
1. [cambio 1] - ADR: Ô£à ADR-0012 / ÔØî FALTA
2. [cambio 2] - ADR: Ô£à ADR-0013 / ÔØî FALTA

VALIDACI├ôN DE FORMATO:
| ADR | Status | Context | Decision | Consequences |
|-----|--------|---------|----------|--------------|
| 0001 | Ô£à | Ô£à | Ô£à | Ô£à |
| 0002 | Ô£à | ÔØî | Ô£à | ÔØî |

ADRs OBSOLETOS:
- ADR-0003: Deprecated (sustituido por ADR-0010)
- ADR-0005: >1 a├▒o sin revisar

ADRS FALTANTES:
1. Decisi├│n de usar [tecnolog├¡a X] - Crear ADR-00XX
2. Migraci├│n a [framework Y] - Crear ADR-00XX

ACCIONES REQUERIDAS:
1. Crear ADR para [cambio sin documentar]
2. Completar secci├│n Consequences en ADR-0002
3. Revisar ADR-0005 (antiguo)
```

---

## Criterios de ├ëxito

- [ ] Todos los cambios arquitect├│nicos tienen ADR
- [ ] ADRs siguen formato est├índar
- [ ] No hay ADRs con status indefinido
- [ ] ADRs obsoletos marcados correctamente

---

## Alertas y Escalaci├│n

| Severidad | Condici├│n | Acci├│n |
|-----------|-----------|--------|
| WARNING | Cambio arquitect├│nico sin ADR | Crear ADR antes de merge |
| WARNING | ADR sin secciones obligatorias | Completar documento |
| INFO | ADR > 1 a├▒o sin revisar | Verificar vigencia |
| INFO | Todo conforme | Documentar buen estado |

---

## Automatizaci├│n

En ejecuci├│n no-interactiva:
1. Escanear carpeta de ADRs
2. Detectar cambios arquitect├│nicos recientes
3. Cruzar cambios con ADRs
4. Validar formato
5. Generar reporte

No crea ADRs autom├íticamente (requiere an├ílisis humano).

---


---

## Output Estructurado (Nexus)

Al finalizar, el agente DEBE generar un bloque JSON con el siguiente formato para que Nexus pueda procesarlo automaticamente:

```json
{
  "result": "success",
  "summary": "Ejecucion de PROC-07 completada. [Descripcion breve de resultados]",
  "metrics": {
    "issues_found": 0,
    "issues_resolved": 0,
    "compliance_percent": 95,
    "custom": {
      "procedure_specific_metric": "value"
    }
  },
  "backlog_items": [
    {
      "title": "Titulo del item de seguimiento",
      "description": "Descripcion detallada si se requiere accion futura",
      "priority": "medium",
      "type": "improvement",
      "tags": ["proc-07"]
    }
  ],
  "next_steps": [
    "Accion recomendada 1",
    "Accion recomendada 2"
  ],
  "warnings": [
    "Advertencias encontradas durante la ejecucion"
  ]
}
```

**Campos requeridos:**
- `result`: `"success"` | `"partial"` | `"failed"`
- `summary`: Resumen ejecutivo en 1-3 lineas

**Metricas especificas de este procedure:**
- adrs_total, adrs_compliant, compliance_percent

**Criterios de resultado:**
- `success`: Procedimiento completado sin errores criticos
- `partial`: Completado con algunos problemas menores o items pendientes
- `failed`: Error critico o no se pudo completar

## Historial de Ejecuciones

| Fecha | Proyecto | ADRs Total | Cambios Sin ADR | Formato OK | Acciones |
|-------|----------|------------|-----------------|------------|----------|
| | | | | | |