Nexus - AI Task Orchestrator

70-tech-debt-analysis
Procedimiento: An├ílisis de Deuda T├®cnica

Dependencias
1 plugin(s)
Titulo
Descripcion
Contenido Markdown
7428 caracteres
# Procedimiento: An├ílisis de Deuda T├®cnica

## Metadata
- **ID**: PROC-70
- **Frecuencia**: Mensual, o antes de planificaci├│n de sprint
- **Duraci├│n estimada**: 2-4 horas
- **Requiere**: Acceso al c├│digo, IDE, conocimiento del proyecto
- **Dependencias**: PROC-04 (tests), PROC-05 (seguridad)
- **Bloquea**: Nada directamente (informa planificaci├│n)

## Objetivo

Identificar, catalogar y priorizar deuda t├®cnica del proyecto para informar decisiones de refactoring y planificaci├│n.

## Categor├¡as de Deuda T├®cnica

| Categor├¡a | Descripci├│n | Impacto | Ejemplo |
|-----------|-------------|---------|---------|
| **Code Quality** | C├│digo dif├¡cil de mantener | Velocidad dev | M├®todos > 100 l├¡neas |
| **Architecture** | Dise├▒o sub├│ptimo | Escalabilidad | Acoplamiento alto |
| **Testing** | Cobertura insuficiente | Confiabilidad | ├üreas sin tests |
| **Documentation** | Docs desactualizados | Onboarding | README obsoleto |
| **Dependencies** | Librer├¡as obsoletas | Seguridad | NuGet packages antiguos |
| **Performance** | C├│digo lento conocido | UX | N+1 queries |
| **Security** | Vulnerabilidades conocidas | Riesgo | Findings Semgrep aceptados |

## Checklist Ejecutable

### 1. An├ílisis de c├│digo con m├®tricas
```bash
cd src

# Archivos m├ís grandes (posibles God classes)
find . -name "*.cs" -exec wc -l {} + | sort -rn | head -20

# M├®todos m├ís largos (requiere herramienta o revisi├│n manual)
# En IDE: buscar m├®todos > 50 l├¡neas

# Clases con m├ís dependencias (constructor injection)
grep -rn "public.*(" src/src/BigCommerceApi/ | grep -c "," | sort -rn | head -10

# TODOs y FIXMEs pendientes
grep -rn "TODO\|FIXME\|HACK\|XXX" src/src/ --include="*.cs"
```

Documentar:

| Archivo | L├¡neas | Problema | Prioridad |
|---------|--------|----------|-----------|
| | | | |

- [ ] Archivos grandes identificados (> 500 l├¡neas)
- [ ] TODOs/FIXMEs catalogados: ___

### 2. An├ílisis de dependencias
```bash
# Listar packages y versiones
dotnet list src/src/BigCommerceApi/BigCommerceApi.csproj package

# Buscar packages desactualizados
dotnet list src/src/BigCommerceApi/BigCommerceApi.csproj package --outdated

# Buscar vulnerabilidades conocidas
dotnet list package --vulnerable
```

| Package | Versi├│n Actual | ├Ültima | Vulnerable | Acci├│n |
|---------|---------------|--------|------------|--------|
| | | | | |

- [ ] Packages outdated: ___
- [ ] Packages vulnerables: ___

### 3. An├ílisis de cobertura de tests
```bash
# Ejecutar con cobertura
dotnet test --collect:"XPlat Code Coverage"

# Ver ├íreas sin cobertura
# Revisar reporte HTML generado
```

| ├ürea | Cobertura | M├¡nimo | Estado |
|------|-----------|--------|--------|
| MCP Tools | ___% | 70% | |
| Services | ___% | 60% | |
| Parsers | ___% | 80% | |

- [ ] ├üreas bajo umbral identificadas

### 4. Revisar c├│digo legacy marcado
```bash
# Buscar c├│digo marcado como obsoleto
grep -rn "\[Obsolete\]" src/
grep -rn "// LEGACY\|// DEPRECATED\|// OLD" src/

# Buscar c├│digo comentado (se├▒al de deuda)
grep -rn "^\s*//.*public\|^\s*//.*private\|^\s*//.*void" src/src/ --include="*.cs"
```

- [ ] C├│digo obsoleto: ___
- [ ] C├│digo comentado a limpiar: ___

### 5. Revisar complejidad ciclom├ítica (manual)

Revisar m├®todos sospechosos:
```csharp
// Se├▒ales de alta complejidad:
// - Muchos if/else anidados
// - Switch con muchos cases
// - M├║ltiples return points
// - Try/catch anidados
```

| M├®todo | Complejidad | Refactor sugerido |
|--------|-------------|-------------------|
| | Alta/Media | |

### 6. Revisar acoplamiento
```bash
# Servicios con muchas dependencias (> 5 en constructor)
grep -A 10 "public.*Service\|public.*Tool" src/src/BigCommerceApi/**/*.cs | grep "private readonly" | wc -l
```

| Clase | # Dependencias | Problema | Sugerencia |
|-------|---------------|----------|------------|
| | | | Split / Facade |

### 7. Catalogar deuda encontrada

Crear/actualizar `docs/tech-debt-backlog.md`:
```markdown
# Tech Debt Backlog

├Ültima actualizaci├│n: YYYY-MM-DD

## Prioridad Alta (Bloquea desarrollo)
| ID | Descripci├│n | ├ürea | Esfuerzo | Impacto |
|----|-------------|------|----------|---------|
| TD-001 | | | S/M/L | Alto |

## Prioridad Media (Ralentiza desarrollo)
| ID | Descripci├│n | ├ürea | Esfuerzo | Impacto |
|----|-------------|------|----------|---------|
| TD-002 | | | S/M/L | Medio |

## Prioridad Baja (Nice to have)
| ID | Descripci├│n | ├ürea | Esfuerzo | Impacto |
|----|-------------|------|----------|---------|
| TD-003 | | | S/M/L | Bajo |
```

- [ ] Backlog actualizado

### 8. Priorizar usando matriz
```
         Impacto Alto    Impacto Bajo
        ÔöîÔöÇÔöÇÔöÇÔöÇÔöÇÔöÇÔöÇÔöÇÔöÇÔöÇÔöÇÔöÇÔöÇÔö¼ÔöÇÔöÇÔöÇÔöÇÔöÇÔöÇÔöÇÔöÇÔöÇÔöÇÔöÇÔöÇÔöÇÔöÉ
EsfuerzoÔöé   HACER     Ôöé   EVALUAR   Ôöé
Bajo    Ôöé   PRIMERO   Ôöé             Ôöé
        Ôö£ÔöÇÔöÇÔöÇÔöÇÔöÇÔöÇÔöÇÔöÇÔöÇÔöÇÔöÇÔöÇÔöÇÔö╝ÔöÇÔöÇÔöÇÔöÇÔöÇÔöÇÔöÇÔöÇÔöÇÔöÇÔöÇÔöÇÔöÇÔöñ
EsfuerzoÔöé   PLANIFICARÔöé   BACKLOG   Ôöé
Alto    Ôöé             Ôöé   O IGNORAR Ôöé
        ÔööÔöÇÔöÇÔöÇÔöÇÔöÇÔöÇÔöÇÔöÇÔöÇÔöÇÔöÇÔöÇÔöÇÔö┤ÔöÇÔöÇÔöÇÔöÇÔöÇÔöÇÔöÇÔöÇÔöÇÔöÇÔöÇÔöÇÔöÇÔöÿ
```

- [ ] Top 3 items a abordar este sprint: ___

## Resultado

- **├ëxito**: Backlog actualizado, prioridades claras, items en sprint
- **Parcial**: Backlog actualizado, sin capacidad para abordar
- **Fallo**: No se pudo analizar ÔåÆ verificar acceso a c├│digo

## Mensaje de Finalizaci├│n

**IMPORTANTE - ACCI├ôN REQUERIDA AL FINALIZAR:**

Cuando hayas completado todos los pasos de este procedimiento, DEBES ejecutar el siguiente comando usando la herramienta Bash:

Ejecuta: `echo "====== PROCESO TERMINADO [$(date +%H%M%S)] ======" && echo "RESULTADO: X items tech debt identificados, Y alta prioridad, Z planificados"`

Sustituye X, Y, Z por los n├║meros reales.


---

## 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-70 completada. [Descripcion breve de resultados]",
  "metrics": {
    "issues_found": 0,
    "issues_resolved": 0,
    "issues_found": 10, "issues_fixed": 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-70"]
    }
  ],
  "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:**
- debt_items_total, debt_items_critical, debt_hours_estimated

**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 | Items Encontrados | Alta | Media | Baja | Resueltos Sprint |
|-------|-------------------|------|-------|------|------------------|
| | | | | | |