---
name: checklist-calidad
description: Evaluación de calidad del trabajo entregado con 7 métricas ponderadas — bugs encontrados, cobertura de tests, conformidad con spec, alucinaciones de código, DRY, seguridad SIGAF y arquitectura. Score ponderado mínimo de 9.0 sobre 10 para aprobar. Produce un reporte con score y plan de mejora.
version: "1.0.0"
herramientasPermitidas: [Read, Grep]
evolvable: true  # default para skill estandar
exclusiones:
  - "No cargar para revisión de seguridad en profundidad (OWASP, CVEs, vulnerabilidades) — para seguridad cargar `checklist-seguridad`."
  - "No cargar para auditoría de dependencias (licencias, CVEs en paquetes) — para dependencias cargar `dependencias-auditoria`."
  - "No cargar para revisión de código por lenguaje específico (Python, TypeScript, SQL) — para revisión por stack cargar el skill del lenguaje correspondiente."
  - "No cargar durante la implementación — se activa AL TERMINAR una fase, no durante el desarrollo."
---
# Habilidad: Checklist de Calidad del Trabajo

## Cuándo NO cargar

- La revisión es de seguridad (OWASP, inyección, auth): cargar `checklist-seguridad`.
- La auditoría es de dependencias (CVEs en paquetes, licencias): cargar `dependencias-auditoria`.
- La revisión es de código fuente por stack específico: cargar el skill del lenguaje (`patrones-python`, `angular-moderno`, etc.).
- Se está en medio de la implementación: este skill se activa al terminar una fase, no durante el desarrollo.

## Propósito

La calidad no es subjetiva — es medible. Esta habilidad aplica 7 métricas
concretas al trabajo entregado y produce un score numérico. Un score menor
a 9.0 bloquea el avance a producción y requiere un plan de mejora explícito.

## Cuándo activar

- Al terminar una fase antes de marcar como "completada"
- Como parte del proceso de revisión de PRs críticos
- Cuando el usuario pide evaluación de calidad del trabajo
- Después de correcciones del verificador para re-evaluar

---

## Métrica 1 — Bugs Encontrados (peso: 25%)

**Definición**: Número de defectos funcionales encontrados durante la verificación.

**Cómo medir**:
1. Ejecutar todos los tests: `pytest -v` / `npm test`
2. Ejecutar el tipo-checker: `mypy .` / `tsc --noEmit`
3. Ejecutar el linter: `ruff check .` / `eslint .`
4. Revisión manual de flujos críticos (happy path + edge cases)

**Escala de puntuación**:
| Bugs encontrados | Puntuación |
|-----------------|-----------|
| 0 bugs | 10.0 |
| 1-2 bugs menores | 8.5 |
| 3-5 bugs menores | 7.0 |
| 1 bug mayor | 5.0 |
| 2+ bugs mayores | 0.0 |

**Bug menor**: no bloquea flujo principal, workaround disponible.
**Bug mayor**: bloquea flujo principal o corrompe datos.

---

## Métrica 2 — Cobertura de Tests (peso: 20%)

**Definición**: Porcentaje de líneas/branches cubiertos por tests automáticos.

**Cómo medir**:
```bash
# Python
pytest --cov=. --cov-report=term-missing --cov-report=html

# TypeScript/Angular
npx jest --coverage
```

**Escala de puntuación**:
| Cobertura | Puntuación |
|-----------|-----------|
| ≥90% | 10.0 |
| 80-89% | 8.5 |
| 70-79% | 7.0 |
| 60-69% | 5.0 |
| <60% | 3.0 |
| Sin tests | 0.0 |

**Nota**: La cobertura de líneas es necesaria pero no suficiente. Verificar
también que los tests tienen assertions reales (ver habilidad `verificar-trabajo`
nivel SUSTANTIVO para tests).

---

## Métrica 3 — Conformidad con Spec (peso: 20%)

**Definición**: Porcentaje de requerimientos del PLAN.md / CONTEXT.md implementados
correctamente.

**Cómo medir**:
1. Listar todos los criterios de aceptación del CONTEXT.md
2. Para cada uno, verificar si está implementado (PASS/FAIL)
3. Score = (criterios PASS / total criterios) * 10

**Puntos de penalización adicional**:
- -1.0: Feature implementada de forma diferente a la spec sin notificación
- -0.5: Feature parcialmente implementada sin documentar qué falta
- -1.5: Feature de seguridad omitida (RBAC, validación, etc.)

---

## Métrica 4 — Alucinaciones de Código (peso: 15%)

**Definición**: Código que parece correcto pero introduce lógica incorrecta,
usa APIs inexistentes o hace suposiciones falsas sobre el sistema.

**Señales a buscar**:
- [ ] Imports de módulos que no existen en el proyecto
- [ ] Llamadas a métodos con firmas incorrectas
- [ ] Variables de entorno asumidas que no están en `.env.example`
- [ ] Endpoints referenciados que no existen en el router
- [ ] Lógica de negocio que contradice los requerimientos documentados
- [ ] Valores hardcodeados que deberían venir de configuración
- [ ] Schemas Pydantic con campos que no existen en el modelo ORM

**Cómo detectar**:
```bash
# Importaciones que no resuelven
mypy . 2>&1 | grep "Cannot find\|Module.*has no attribute"

# Variables de entorno sin documentar
grep -rn "os\.getenv\|os\.environ" --include="*.py" | \
  awk '{print $2}' | sort | uniq > env_usados.txt
grep -rn "^[A-Z_]*=" .env.example | awk -F= '{print $1}' | sort > env_documentados.txt
diff env_usados.txt env_documentados.txt
```

**Escala de puntuación**:
| Alucinaciones | Puntuación |
|--------------|-----------|
| 0 | 10.0 |
| 1-2 menores (import inexistente, typo) | 7.0 |
| 1 mayor (lógica incorrecta) | 4.0 |
| 2+ mayores | 0.0 |

---

## Métrica 5 — Principio DRY (peso: 10%)

**Definición**: No repetición innecesaria de lógica o código.

**Cómo medir** — buscar duplicación:
```bash
# Funciones similares (Python)
# Herramienta: pylint, sonarqube o revisión manual
grep -rn "def " --include="*.py" | awk -F: '{print $3}' | sort | uniq -d | head -20

# Bloques de código > 10 líneas idénticos
# Revisión manual de services y utils
```

**Items a verificar**:
- [ ] Sin funciones duplicadas entre módulos
- [ ] Sin queries SQL duplicadas que deberían ser un helper
- [ ] Sin lógica de validación repetida que debería estar en un validator
- [ ] Sin constantes definidas en múltiples lugares
- [ ] Sin componentes Angular que hacen lo mismo con diferente nombre

**Escala**:
| DRY violations | Puntuación |
|---------------|-----------|
| 0 | 10.0 |
| 1-2 menores | 8.0 |
| 3-5 | 6.0 |
| 5+ o duplicación de lógica crítica | 3.0 |

---

## Métrica 6 — Seguridad SIGAF (peso: 5%)

**Definición**: Cumplimiento de las reglas anti-error SIGAF documentadas en el
sistema. Esta métrica es binaria por categoría.

**Checklist SIGAF**:
- [ ] selectinload en todas las relaciones accedidas en serialización
- [ ] lazy="selectin" en relaciones a Usuario
- [ ] Services no hacen db.commit()
- [ ] Literal[] en campos enum en schemas Pydantic
- [ ] RBAC en todos los POST/PUT/DELETE
- [ ] get_current_user explícito en todos los endpoints
- [ ] Filtros de datos del JWT, no de query params
- [ ] @if/@for en Angular (no *ngIf/*ngFor)
- [ ] computed() para derivaciones en templates

**Escala**:
| Items fallidos | Puntuación |
|---------------|-----------|
| 0 | 10.0 |
| 1 | 7.0 |
| 2 | 4.0 |
| 3+ | 0.0 |

---

## Métrica 7 — Arquitectura (peso: 5%)

**Definición**: El código nuevo respeta las capas y convenciones del proyecto.

**Items a verificar**:
- [ ] Services no importan directamente modelos de otros dominios (bypassing capas)
- [ ] Endpoints no tienen lógica de negocio incrustada (lógica en services)
- [ ] Componentes Angular no hacen llamadas HTTP directamente (usan services)
- [ ] Modelos ORM no tienen lógica de negocio compleja (en services)
- [ ] No se introdujeron nuevas dependencias sin justificación documentada

---

## Gotchas / Errores comunes no obvios

**La Métrica 2 (cobertura) pasa al 85% pero todos los tests son de happy path**: la cobertura de líneas no detecta que los tests omiten los casos de error, los inputs nulos y los edge cases. Causa: es más fácil alcanzar 80% cubriendo el flujo principal que cubriendo los branches de validación. Fix: complementar el porcentaje de cobertura con revisión manual de qué branches están sin cubrir — `pytest --cov-branch` reporta cobertura de branches, no solo de líneas. Un 80% de branch coverage es más significativo que un 90% de line coverage.

**La Métrica 4 (alucinaciones) pasa porque `mypy` no detecta errores, pero hay lógica incorrecta**: `mypy` verifica tipos, no semántica de negocio. Un endpoint que siempre devuelve `200 OK` aunque la operación falle, o una función que suma precios en lugar de multiplicar, pasa todos los type checks. Causa: las alucinaciones semánticas son invisibles para el análisis estático. Fix: la Métrica 4 requiere revisión manual del flujo de negocio crítico, no solo ejecutar herramientas automáticas. Verificar que la lógica implementada coincide con los criterios de aceptación del PLAN.md.

**El score final es 9.2 pero hay un item de seguridad SIGAF fallido con "penalización mínima"**: la Métrica 6 tiene peso solo del 5%, por lo que un RBAC faltante baja el score de 10 a 9.5 — por encima del umbral de 9.0. Causa: el sistema de pesos numéricos permite que un defecto de seguridad crítico quede diluido por buenas métricas en otras categorías. Fix: los ítems de la Métrica 6 son veto independiente del score: si algún ítem de RBAC, selectinload o get_current_user falla, el veredicto es RECHAZADO independientemente del score ponderado.

**La Métrica 3 (conformidad con spec) puntúa 10/10 porque el implementador revisó su propia spec**: el agente que implementó el código también evalúa si cumple los criterios que él mismo escribió. Causa: la Métrica 3 requiere contrastar el código contra criterios externos, no autoevaluación. Fix: la conformidad con spec debe verificarse contra el PLAN.md aprobado, no contra la memoria del implementador. Leer el PLAN.md antes de puntuar la Métrica 3 y citar el número de criterio de aceptación que cada ítem satisface.

## Cálculo del score final

```
Score = (M1 * 0.25) + (M2 * 0.20) + (M3 * 0.20) + (M4 * 0.15)
      + (M5 * 0.10) + (M6 * 0.05) + (M7 * 0.05)
```

| Score | Veredicto |
|-------|-----------|
| 9.0 - 10.0 | APROBADO |
| 7.0 - 8.9 | APROBADO CON OBSERVACIONES (debe mejorarse antes de siguiente fase) |
| 5.0 - 6.9 | RECHAZADO — requiere trabajo de corrección |
| < 5.0 | RECHAZADO CRÍTICO — requiere reescritura parcial |

---

## Plantilla de reporte: `QUALITY-REPORT.md`

```markdown
# QUALITY-REPORT.md — Fase [N]
**Fecha**: [fecha]  **Evaluador**: [agente/persona]

## Score Final: [X.X / 10.0] — [VEREDICTO]

## Desglose de métricas
| # | Métrica | Peso | Puntuación | Score ponderado |
|---|---------|------|-----------|----------------|
| 1 | Bugs encontrados | 25% | [X]/10 | [X*0.25] |
| 2 | Cobertura de tests | 20% | [X]/10 | [X*0.20] |
| 3 | Conformidad con spec | 20% | [X]/10 | [X*0.20] |
| 4 | Alucinaciones | 15% | [X]/10 | [X*0.15] |
| 5 | DRY | 10% | [X]/10 | [X*0.10] |
| 6 | Seguridad SIGAF | 5% | [X]/10 | [X*0.05] |
| 7 | Arquitectura | 5% | [X]/10 | [X*0.05] |
| **TOTAL** | | **100%** | | **[SCORE]** |

## Hallazgos por métrica
[Para cada métrica con puntuación < 9.0, listar los hallazgos específicos]

## Plan de mejora (si score < 9.0)
| Acción | Impacto en score | Tiempo estimado | Prioridad |
|--------|----------------|----------------|----------|
|        |                |                |          |

## Decisión
[ ] Aprobar para siguiente fase
[ ] Aprobar con compromisos de mejora
[ ] Rechazar — requiere iteración
```
