Nexus - AI Task Orchestrator

01-documentation-maintenance
Procedimiento: Actualizaci├│n y Mantenimiento de la Documentaci├│n

Documentacion
1 plugin(s)
Titulo
Descripcion
Contenido Markdown
14345 caracteres
# Procedimiento: Actualizaci├│n y Mantenimiento de la Documentaci├│n

## Metadata
- **ID**: PROC-01
- **Frecuencia**: Semanal, post-merge a `main`, o pre-release
- **Duraci├│n estimada**: 15-45 min (seg├║n scope)
- **Requiere**: Acceso al repositorio git
- **Dependencias**: Ninguna
- **Bloquea**: Releases (documentaci├│n debe estar sincronizada)
- **SLA**: Drift < 10% entre c├│digo y documentaci├│n

---

## ­ƒÜÇ Inicio R├ípido

**Para ejecutar este procedimiento, el agente debe:**

### 0. Detectar estructura del proyecto

El sistema de agentes puede estar en diferentes ubicaciones. Buscar en orden:
1. `docs/.ai/` (Calmia v2 standard)
2. `src/docs/.ai/` (legacy structure)
3. `src/docs/ai-orchestrator/` (legacy v1)

Una vez encontrada la carpeta `.ai` o `ai-orchestrator`, usar esa ruta como `$AI_PATH`.

### 1. Cargar estos archivos (en orden):

Buscar y cargar desde `$AI_PATH`:
```
$AI_PATH/agents/documentation-architect.md
$AI_PATH/agents/documentation-engineer.md
$AI_PATH/commands/docs-sync.md
$AI_PATH/commands/docs-doctor.md
$AI_PATH/skills/documentation-standards/SKILL.md
$AI_PATH/skills/documentation-standards/diataxis.md
```

Si alguno no existe, continuar con los disponibles.

### 2. Determinar modo de ejecuci├│n:

| Modo | Cu├índo usar | Comando rango |
|------|-------------|---------------|
| **full** | Primera vez, reset completo | `--from $(git rev-list --max-parents=0 HEAD)` |
| **release** | Pre-release, post-tag | `--from $(git describe --tags --abbrev=0)` |
| **weekly** | Mantenimiento semanal | `--from $(git log -1 --format=%ci --before="7 days ago")` |
| **incremental** | Post-merge | `--from $(git merge-base HEAD main~1)` |

### 3. Determinar modo (auto-selecci├│n para ejecuci├│n no-interactiva):

**Si se ejecuta via WhatsApp/automatizaci├│n (sin terminal interactiva):**
- Usar modo **weekly** por defecto autom├íticamente
- NO preguntar al usuario, proceder directamente
- Log: "Modo no-interactivo detectado, usando weekly por defecto"

**Si se ejecuta manualmente (terminal interactiva disponible):**
> "┬┐Qu├® tipo de sincronizaci├│n necesitas?"
> 1. **Full** - Documentar todo desde el inicio (primera vez o reset)
> 2. **Release** - Desde el ├║ltimo tag de release
> 3. **Semanal** - Cambios de la ├║ltima semana
> 4. **Incremental** - Solo cambios recientes

**Detecci├│n de modo no-interactivo:**
- Si `$NON_INTERACTIVE` est├í definido ÔåÆ no-interactivo
- Si no hay stdin disponible ÔåÆ no-interactivo
- Si viene de MaintenanceWorker/RabbitMQ ÔåÆ no-interactivo

---

## Scope de Documentaci├│n

> **Nota**: Las rutas var├¡an seg├║n la estructura del proyecto.
> Detectar `$DOCS_PATH` (puede ser `docs/`, `src/docs/`, o similar).

### Archivos incluidos

| Archivo/Carpeta | Descripci├│n | Siempre incluir |
|-----------------|-------------|-----------------|
| `README.md` (ra├¡z) | Overview del proyecto, quickstart | Ô£à S├¡ |
| `$DOCS_PATH/*.md` | Documentaci├│n t├®cnica | Ô£à S├¡ |
| `$DOCS_PATH/index.md` | Mapa de navegaci├│n (crear si no existe) | Ô£à S├¡ |
| `$DOCS_PATH/_meta/` | Configuraci├│n docs (crear si no existe) | Ô£à S├¡ |

### Archivos excluidos

- `$AI_PATH/procedures/` - Son procedimientos, no documentaci├│n de c├│digo
- `$AI_PATH/` - Es el sistema de agentes
- `$DOCS_PATH/postman/` - Colecciones Postman (si existe)
- `**/bin/`, `**/obj/`, `**/node_modules/`

---

## Ejecuci├│n del Procedimiento

### Fase 1: Diagn├│stico

```
Ejecutar: /docs:doctor
```

**Acciones del agente:**
1. Analizar estructura actual de `$DOCS_PATH/`
2. Verificar si existe `README.md` en ra├¡z
3. Contar items documentados vs items en c├│digo
4. Generar score de salud

**Output esperado:**
- Score: X/100
- Gaps identificados
- Recomendaciones priorizadas

---

### Fase 2: Preparar Estructura (si es modo full o no existe)

Si no existe `$DOCS_PATH/_meta/`, crear:

**$DOCS_PATH/_meta/doc-config.yml:**
```yaml
project:
  name: "{{PROJECT_NAME}}"
  type: "api"
  
structure:
  root: "$DOCS_PATH/"
  readme: "README.md"  # En ra├¡z del proyecto

sync:
  code_paths:
    - "src/"
  exclude_paths:
    - "$DOCS_PATH/"
    - "tests/"
    - "bin/"
    - "obj/"
```

**$DOCS_PATH/_meta/doc-map.yml:**
```yaml
# Mapeo c├│digo ÔåÆ documentaci├│n
modules:
  mcp-tools:
    code_paths: ["src/src/*/Mcp/Tools/"]
    docs:
      reference: "20-mcp-tools.md"
      
  # ... mapear cada m├│dulo
```

**$DOCS_PATH/index.md** (si no existe):
```markdown
# Documentaci├│n del Proyecto

## Navegaci├│n

### Arquitectura
- [Overview](00-overview.md)
- [Arquitectura](10-architecture.md)

### Features
- [MCP Tools](20-mcp-tools.md)
- ...

### Operaciones
- [Runbook](32-operations-runbook.md)
- [Troubleshooting](80-troubleshooting.md)
```

---

### Fase 3: Sincronizaci├│n

```
Ejecutar: /docs:sync --from {{RANGO}} --mode full
```

**Pipeline interno:**

1. **Scan** - Detectar cambios en c├│digo
2. **Map** - Identificar docs afectados via doc-map
3. **Update** - Actualizar/crear documentaci├│n
4. **README** - Actualizar README.md de ra├¡z si hay cambios relevantes
5. **Prune** - Eliminar docs de c├│digo que ya no existe
6. **Verify** - Validar coherencia

**Para README.md espec├¡ficamente:**
- Actualizar secci├│n "Features" si hay nuevos m├│dulos
- Actualizar "Quick Start" si cambia la instalaci├│n
- Actualizar badges/versiones si aplica
- Mantener estructura existente, no reescribir todo

---

### Fase 3.5: Verificaci├│n Expl├¡cita de README.md (OBLIGATORIA)

ÔÜá´©Å **CR├ìTICO**: El README.md de la ra├¡z NO se actualiza autom├íticamente. Debe verificarse manualmente.

**Checklist README.md:**

```
1. Abrir README.md de la ra├¡z del proyecto
2. Buscar m├®tricas num├®ricas (counts de tools, endpoints, etc.)
3. Comparar con valores reales del c├│digo
4. Actualizar si hay discrepancias
```

**B├║squeda de m├®tricas desactualizadas:**
```bash
# Buscar n├║meros que podr├¡an estar desactualizados
grep -E "[0-9]+ (tools|endpoints|MCP|APIs)" README.md

# Comparar con count real (ejemplo para MCP tools)
find src -name "*Tool.cs" -type f | wc -l
```

**Secciones a verificar en README.md:**

| Secci├│n | Qu├® verificar |
|---------|---------------|
| T├¡tulo/Badge | Versi├│n, status badges |
| Descripci├│n | N├║mero de tools/features mencionado |
| Arquitectura (diagramas ASCII) | Counts en diagramas (ej: "MCP Tools (55)") |
| Features list | Todos los m├│dulos principales listados |
| Quick Start | Comandos actualizados |
| Endpoints table | Todos los endpoints documentados |

**Si encuentras discrepancias:**
```bash
# Ejemplo: actualizar "38" a "55" en README.md
sed -i 's/38 tools/55 tools/g' README.md
sed -i 's/MCP Tools (38)/MCP Tools (55)/g' README.md
```

**Output obligatorio:**
```
README.md verification:
- Metrics found: X
- Updated: Y (list changes)
- Status: Ô£à Synced | ÔÜá´©Å Manual review needed
```

---

### Fase 4: Verificaci├│n General

**Checklist autom├ítico:**

| Check | Comando/Acci├│n |
|-------|----------------|
| Build OK | `dotnet build --no-restore` |
| **README.md m├®tricas** | **Comparar counts c├│digo vs README** |
| Tools documentadas | Comparar count c├│digo vs docs |
| Sin TODOs hu├®rfanos | `grep -r "TODO\|FIXME" $DOCS_PATH/*.md` |
| Links internos v├ílidos | Verificar referencias cruzadas |

**M├®tricas finales:**
```
DOC_SYNC_RESULT = OK/FAIL
Score: X/100
Drift: X%

README.md Status:
- Checked: Yes
- Metrics found: X
- Updated: Yes/No (list if yes)

Files: X updated, X created, X removed
```

---

### Fase 5: Commit

```bash
git add README.md $DOCS_PATH/
git commit -m "docs: sync documentation [PROC-01]

Mode: {{full|release|weekly|incremental}}
Range: {{FROM}}..HEAD

Changes:
- README.md: {{updated|no changes}}
- Updated: {{list}}
- Created: {{list}}
- Removed: {{list}}

Score: {{X}}/100 | Drift: {{X}}%"
```

---

## Comportamiento por Modo

### Modo: full (primera vez)

1. Crear estructura completa `_meta/`
2. Crear `index.md` con navegaci├│n
3. Escanear TODO el c├│digo
4. Documentar TODOS los m├│dulos
5. Actualizar README.md completamente
6. Crear doc-map.yml completo

### Modo: release

1. Escanear desde ├║ltimo tag
2. Actualizar solo docs afectados
3. Verificar README.md (actualizar si hay features nuevas)
4. Actualizar versi├│n en docs si aplica

### Modo: weekly

1. Escanear ├║ltima semana
2. Actualizar docs modificados
3. Quick check de README.md
4. Podar si hay c├│digo eliminado

### Modo: incremental

1. Escanear solo commits recientes
2. Actualizar m├¡nimo necesario
3. No tocar README.md salvo cambio mayor

---

## Troubleshooting

| Problema | Soluci├│n |
|----------|----------|
| "No encuentro doc-map.yml" | Ejecutar en modo `full` primero |
| "README.md muy diferente" | Preservar estructura, actualizar secciones |
| "Drift > 25%" | Dividir en sprints, documentar por m├│dulo |
| "Score < 50" | Sesi├│n dedicada de documentaci├│n |

---

## Ejemplo de Invocaci├│n

### Ejecuci├│n interactiva (terminal manual)

**Usuario dice:**
> "Ejecuta PROC-01" o "Ejecuta el procedimiento de documentaci├│n"

**Agente responde:**
> "Voy a ejecutar PROC-01 (Documentaci├│n). ┬┐Qu├® modo necesitas?"
> 1. Full - Documentar todo desde inicio
> 2. Release - Desde ├║ltimo tag
> 3. Weekly - ├Ültima semana
> 4. Incremental - Cambios recientes
>
> (Si no especificas, usar├® **weekly** por defecto)

**Usuario dice:**
> "Full, es la primera vez"

**Agente:**
> "Perfecto. Cargando agentes de documentaci├│n y ejecutando sync completo..."
> [Carga archivos listados en Inicio R├ípido]
> [Ejecuta /docs:doctor]
> [Ejecuta /docs:sync --from primer-commit --mode full]
> [Reporta resultados]

### Ejecuci├│n no-interactiva (WhatsApp/automatizaci├│n)

**Mensaje WhatsApp:**
> "ejecutar procedimiento 01 en bigcommerce"

**Agente (NO pregunta, ejecuta directamente):**
> "Modo no-interactivo detectado. Ejecutando PROC-01 con modo weekly por defecto..."
> [Carga archivos listados en Inicio R├ípido]
> [Ejecuta /docs:doctor]
> [Ejecuta /docs:sync --from 7-days-ago --mode weekly]
> [Reporta resultados]
> [Notifica via WhatsApp al completar]

---

## Mensaje de Finalizaci├│n

Al completar, ejecutar:

```bash
echo "====== PROC-01 COMPLETADO [$(date +%H%M%S)] ======"
echo "Modo: {{MODE}}"
echo "Score: {{SCORE}}/100"
echo "Drift: {{DRIFT}}%"
echo ""
echo "README.md (ra├¡z):"
echo "  - Verificado: Ô£à"
echo "  - M├®tricas actualizadas: {{list or 'ninguna'}}"
echo ""
echo "Archivos: {{N}} actualizados, {{N}} creados, {{N}} eliminados"
```

---

### Fase 6: Generar Project Context (para Claude/ChatGPT Projects)

**Objetivo:** Crear un archivo compacto con el contexto esencial del proyecto, optimizado para subir a Claude Projects o ChatGPT Projects.

**Destino:** `Z:\Sync\claude-projects\{nombre-proyecto}\project-context.md`

**Contenido del archivo (m├íximo 2-3 p├íginas):**

```markdown
# {Nombre del Proyecto} - Context

## Descripci├│n
{Descripci├│n breve del proyecto en 2-3 l├¡neas}

## Stack Tecnol├│gico
- **Runtime**: {.NET 8, Node.js, etc.}
- **Framework**: {ASP.NET Core, Express, etc.}
- **Base de datos**: {SQL Server, PostgreSQL, etc.}
- **Otros**: {RabbitMQ, Redis, etc.}

## Estructura del Proyecto
```
{├írbol simplificado de carpetas principales}
```

## Agentes Recomendados
| Agente | Uso |
|--------|-----|
| {nombre} | {descripci├│n breve} |

## Procedures Disponibles
| ID | Nombre | Frecuencia |
|----|--------|------------|
| PROC-XX | {nombre} | {frecuencia} |

## Documentaci├│n Principal
- [README](ruta/README.md) - Overview y quickstart
- [Arquitectura](ruta/10-architecture.md) - Dise├▒o del sistema
- [API Reference](ruta/20-api.md) - Endpoints y contratos

## Convenciones del Proyecto
- {Convenci├│n 1}
- {Convenci├│n 2}

## Comandos Frecuentes
```bash
dotnet build        # Compilar
dotnet test         # Tests
dotnet run          # Ejecutar
```
```

**Acciones del agente:**

1. Crear carpeta destino si no existe:
   ```bash
   mkdir -p "Z:\Sync\claude-projects\{nombre-proyecto}"
   ```

2. Generar contenido analizando:
   - README.md del proyecto
   - Estructura de carpetas
   - Archivos .csproj/.sln (para .NET) o package.json (para Node)
   - `$AI_PATH/agents/` disponibles
   - `$AI_PATH/procedures/` disponibles

3. Escribir `project-context.md` en destino

4. Reportar:
   ```
   Project Context generado:
   - Destino: Z:\Sync\claude-projects\{nombre}\project-context.md
   - Tama├▒o: X KB
   - Secciones: {lista}
   ```

**Nota:** Este archivo est├í dise├▒ado para ser subido manualmente a:
- Claude Projects (claude.ai/projects)
- ChatGPT Projects (chatgpt.com)
- Cualquier LLM que soporte contexto de proyecto

---

## Output Estructurado (Nexus)

Al finalizar, el agente DEBE generar un bloque JSON con el siguiente formato para que Nexus pueda procesarlo autom├íticamente:

```json
{
  "result": "success",
  "summary": "Sincronizaci├│n de documentaci├│n completada. Score 85/100, drift 8%. README.md actualizado con nuevas m├®tricas de MCP tools.",
  "metrics": {
    "issues_found": 3,
    "issues_resolved": 3,
    "files_analyzed": 45,
    "files_updated": 7,
    "score": 85,
    "custom": {
      "drift_percent": 8,
      "readme_updated": true,
      "mode": "weekly"
    }
  },
  "backlog_items": [
    {
      "title": "Documentar nuevo m├│dulo de autenticaci├│n",
      "description": "El m├│dulo AuthService fue a├▒adido pero no tiene documentaci├│n en 20-services.md",
      "priority": "medium",
      "type": "improvement"
    }
  ],
  "next_steps": [
    "Revisar PR #123 con los cambios de documentaci├│n",
    "Actualizar diagrama de arquitectura si hay cambios mayores"
  ],
  "warnings": [
    "README.md ten├¡a m├®tricas desactualizadas (38 tools -> 55 tools)"
  ]
}
```

**Campos requeridos:**
- `result`: "success" | "partial" | "failed"
- `summary`: Resumen ejecutivo en 1-3 l├¡neas

**Campos opcionales pero recomendados:**
- `metrics`: M├®tricas cuantitativas de la ejecuci├│n
- `backlog_items`: Items de seguimiento para crear en Nexus
- `next_steps`: Acciones recomendadas post-ejecuci├│n
- `warnings`: Advertencias encontradas durante la ejecuci├│n

**Criterios de resultado:**
- `success`: Score >= 80%, drift < 10%, sin errores bloqueantes
- `partial`: Score >= 60%, drift < 25%, algunos archivos pendientes
- `failed`: Score < 60% o error cr├¡tico

---

## Historial de Ejecuciones

| Fecha | Modo | Score | Drift | README | Context | Notas |
|-------|------|-------|-------|--------|---------|-------|
| | | | | | | |