Nexus - AI Task Orchestrator

03-readme-health-check
Procedimiento: README Health Check

Documentacion
1 plugin(s)
Titulo
Descripcion
Contenido Markdown
7925 caracteres
# Procedimiento: README Health Check

## Metadata
- **ID**: PROC-03
- **Frecuencia**: Semanal
- **Duraci├│n estimada**: 10-20 min
- **Requiere**: Acceso al repositorio
- **Dependencias**: Ninguna
- **Bloquea**: Ninguno
- **Agentes**: documentation-architect

---

## Objetivo

Verificar que los archivos README del proyecto:
1. Existen en las ubicaciones requeridas
2. Contienen las secciones obligatorias
3. Est├ín actualizados respecto al c├│digo
4. Tienen m├®tricas correctas (counts, versiones)

---

## Secciones Obligatorias

### README.md (Ra├¡z del Proyecto)

| Secci├│n | Obligatoria | Descripci├│n |
|---------|-------------|-------------|
| T├¡tulo + Badges | S├¡ | Nombre del proyecto, badges de CI/CD |
| Descripci├│n | S├¡ | Qu├® hace el proyecto (1-3 l├¡neas) |
| Quick Start | S├¡ | C├│mo ejecutar en < 5 pasos |
| Arquitectura | Recomendado | Diagrama o descripci├│n de componentes |
| API/Endpoints | Si aplica | Tabla de endpoints principales |
| Configuraci├│n | S├¡ | Variables de entorno, archivos config |
| Desarrollo | Recomendado | C├│mo contribuir, setup local |
| Licencia | Si es p├║blico | Tipo de licencia |

### README.md (Subcarpetas)

- `src/README.md` - Estructura del c├│digo fuente
- `docs/README.md` - ├ìndice de documentaci├│n
- `tests/README.md` - C├│mo ejecutar tests

---

## Checklist Ejecutable

### 1. Verificar Existencia de READMEs

```bash
# READMEs que deben existir
find . -maxdepth 1 -name "README.md" -type f
find ./src -maxdepth 1 -name "README.md" -type f 2>/dev/null
find ./docs -maxdepth 1 -name "README.md" -type f 2>/dev/null

# Listar todos los READMEs del proyecto
find . -name "README.md" -type f | grep -v node_modules | grep -v bin | grep -v obj
```

- [ ] README.md existe en ra├¡z
- [ ] README.md existe en docs/ (si existe la carpeta)

### 2. Validar Secciones del README Principal

```bash
# Verificar secciones principales (buscar headers ##)
grep -E "^#+\s+" README.md

# Secciones esperadas:
# - T├¡tulo (# Nombre)
# - Descripci├│n o Overview
# - Quick Start o Getting Started o Installation
# - Configuration o Setup
# - API o Endpoints (si aplica)
```

**Checklist de secciones:**

- [ ] Tiene t├¡tulo (# Proyecto)
- [ ] Tiene descripci├│n breve
- [ ] Tiene Quick Start / Getting Started
- [ ] Tiene secci├│n de Configuraci├│n
- [ ] Tiene secci├│n de Arquitectura (recomendado)
- [ ] Tiene badges de CI/CD (recomendado)

### 3. Validar M├®tricas Num├®ricas

```bash
# Buscar n├║meros que podr├¡an desactualizarse
grep -oE "[0-9]+ (tools?|endpoints?|APIs?|features?|modules?)" README.md

# Comparar con realidad
# Para proyectos .NET - contar controladores/endpoints
find src -name "*Controller.cs" -type f | wc -l
grep -r "\[Http" src --include="*.cs" | wc -l

# Para proyectos Node - contar rutas
grep -r "router\." src --include="*.js" --include="*.ts" | wc -l
```

- [ ] N├║meros en README coinciden con c├│digo
- [ ] Versiones mencionadas est├ín actualizadas

### 4. Validar Enlaces Internos

```bash
# Extraer enlaces a archivos locales
grep -oE "\[.*\]\(\.?/?[^http][^)]+\)" README.md

# Verificar que cada enlace existe
# Para cada enlace encontrado:
# test -f "path/to/file" && echo "OK" || echo "ROTO: path/to/file"
```

- [ ] Todos los enlaces internos funcionan
- [ ] No hay referencias a archivos eliminados

### 5. Validar Comandos de Quick Start

```bash
# Extraer bloques de c├│digo con comandos
grep -A5 "```bash\|```shell\|```sh" README.md

# Verificar que los comandos son v├ílidos
# - Archivos referenciados existen
# - Scripts mencionados existen
# - Comandos dotnet/npm son correctos
```

- [ ] Comandos de instalaci├│n funcionan
- [ ] Scripts referenciados existen
- [ ] Paths son correctos

### 6. Verificar Fecha de ├Ültima Actualizaci├│n

```bash
# ├Ültima modificaci├│n del README
git log -1 --format="%ci %s" -- README.md

# Comparar con ├║ltimos cambios significativos en src/
git log -1 --format="%ci" -- src/

# Si README es muy viejo vs c├│digo, necesita revisi├│n
```

- [ ] README actualizado en los ├║ltimos 30 d├¡as
- [ ] O no hubo cambios significativos en c├│digo

---

## Puntuaci├│n de Salud

| Criterio | Puntos | M├íximo |
|----------|--------|--------|
| README existe en ra├¡z | 20 | 20 |
| T├¡tulo + descripci├│n | 10 | 10 |
| Quick Start presente | 15 | 15 |
| Quick Start funcional | 15 | 15 |
| Configuraci├│n documentada | 10 | 10 |
| M├®tricas correctas | 10 | 10 |
| Enlaces funcionan | 10 | 10 |
| Actualizado (<30 d├¡as) | 10 | 10 |
| **TOTAL** | | **100** |

### Interpretaci├│n

| Score | Estado | Acci├│n |
|-------|--------|--------|
| 90-100 | Excelente | Mantener |
| 70-89 | Bueno | Mejoras menores |
| 50-69 | Regular | Necesita atenci├│n |
| <50 | Cr├¡tico | Actualizaci├│n urgente |

---

## Output Esperado

```
====== PROC-03 COMPLETADO [TIMESTAMP] ======
Proyecto: [nombre]

ARCHIVOS README:
- README.md (ra├¡z): Ô£à Existe
- docs/README.md: Ô£à Existe / ÔØî No existe
- src/README.md: ÔÜá´©Å Opcional

SECCIONES README PRINCIPAL:
- T├¡tulo: Ô£à
- Descripci├│n: Ô£à
- Quick Start: Ô£à / ÔØî
- Configuraci├│n: Ô£à / ÔØî
- Arquitectura: ÔÜá´©Å Recomendado
- Badges CI: ÔÜá´©Å Recomendado

M├ëTRICAS:
- Endpoints en README: X
- Endpoints en c├│digo: Y
- Estado: Ô£à Correcto / ÔØî Desactualizado

ENLACES:
- Total: X
- Funcionando: Y
- Rotos: Z [lista]

├ÜLTIMA ACTUALIZACI├ôN:
- README: [fecha]
- C├│digo: [fecha]
- Estado: Ô£à Sincronizado / ÔÜá´©Å Revisar

SCORE: XX/100
Estado: [Excelente/Bueno/Regular/Cr├¡tico]

ACCIONES REQUERIDAS:
1. [acci├│n si hay]
2. [acci├│n si hay]
```

---

## Criterios de ├ëxito

- [ ] Score >= 70
- [ ] No hay enlaces rotos
- [ ] Quick Start funciona
- [ ] M├®tricas correctas

---

## Alertas y Escalaci├│n

| Severidad | Condici├│n | Acci├│n |
|-----------|-----------|--------|
| WARNING | Score < 70 | Crear tarea Holded para actualizar |
| WARNING | Enlaces rotos > 0 | Corregir inmediatamente |
| WARNING | README > 60 d├¡as sin actualizar | Revisar si necesita cambios |
| INFO | Score >= 90 | Documentar buen estado |

---

## Automatizaci├│n

En ejecuci├│n no-interactiva:
1. Verificar existencia de archivos
2. Parsear secciones
3. Validar enlaces
4. Calcular score
5. Reportar resultados

No requiere interacci├│n manual.

---


---

## 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-03 completada. [Descripcion breve de resultados]",
  "metrics": {
    "issues_found": 0,
    "issues_resolved": 0,
    "score": 85, "drift_percent": 8,
    "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-03"]
    }
  ],
  "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:**
- readme_sections, issues_found, issues_fixed

**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 | Score | Secciones OK | Enlaces Rotos | Acciones |
|-------|----------|-------|--------------|---------------|----------|
| | | | | | |