workspace-v1/orchestration/checklists/CHECKLIST-REFACTORIZACION.md

CHECKLIST DE REFACTORIZACIÓN

Versión: 1.0.0 Fecha creación: 2025-11-23 Proyecto: GAMILIT - Sistema de Gamificación Educativa Estado: Directiva Obligatoria

---

🎯 PROPÓSITO

Este checklist es OBLIGATORIO para toda refactorización de código en el proyecto GAMILIT. Su objetivo es prevenir bugs, imports rotos y regresiones.

Problemas que previene:

• ❌ Imports rotos que causan caída del frontend (BUG-FRONTEND-001)
• ❌ Rutas hard-coded incorrectas (BUG-FRONTEND-002)
• ❌ Refactorizaciones incompletas
• ❌ Breaking changes no detectados

---

✅ CHECKLIST COMPLETO

FASE 1: PRE-REFACTORIZACIÓN (Planificación)

1.1 Análisis de Dependencias

• Identificar archivos a modificar/mover/eliminar

  • Listar TODOS los archivos afectados
  • Incluir archivos de código, tests, docs, configs

• Identificar dependencias

  # Para archivos a mover/eliminar:
  grep -r "from.*nombre-archivo" apps/
  grep -r "import.*nombre-archivo" apps/
  

  • Listar TODOS los archivos que importan el código a refactorizar
  • Verificar imports relativos vs absolutos
  • Buscar dynamic imports (import())

• Analizar impacto

  • ¿Cuántos archivos se verán afectados?
  • ¿Hay código crítico que depende de esto?
  • ¿Afecta a múltiples módulos/capas?

1.2 Documentación del Plan

• Crear documento de plan de refactorización

  • Ubicación: orchestration/agentes/{agente}/refactor-{nombre}-{fecha}/PLAN.md
  • Incluir: objetivo, archivos afectados, estrategia, rollback plan

• Estimar esfuerzo completo

  • Tiempo de implementación de cambios
  • Tiempo de actualización de referencias
  • Tiempo de testing
  • Tiempo de documentación
  • NO subestimar (considerar TODO el trabajo, no solo el cambio principal)

• Definir criterios de éxito

  • ¿Cómo validar que refactorización fue exitosa?
  • ¿Qué tests deben pasar?
  • ¿Qué funcionalidades deben seguir funcionando?

1.3 Preparación del Entorno

• Crear rama nueva

  git checkout -b refactor/nombre-descriptivo
  

• Asegurar que código actual funciona

  npm run build
  npm run test
  npm run dev  # Validar que servidor inicia
  

  • ✅ Build exitoso
  • ✅ Tests pasando
  • ✅ Servidor inicia sin errores

• Commit inicial (snapshot)

  git add .
  git commit -m "chore: snapshot before refactor {nombre}"
  

---

FASE 2: DURANTE REFACTORIZACIÓN (Implementación)

2.1 Implementación de Cambios

• Mover/crear archivos nuevos

  • Usar herramientas de refactorización del IDE cuando sea posible
  • Copiar primero, eliminar después (mantener versión anterior temporalmente)

• Actualizar TODOS los imports

  • Usar búsqueda global para encontrar ALL references
  • Actualizar imports en archivos de código
  • Actualizar imports en tests
  • Actualizar dynamic imports
  • Actualizar re-exports (index.ts)

• Verificar imports con búsqueda global

  # Verificar que NO queden referencias al archivo antiguo
  grep -r "from.*nombre-archivo-antiguo" apps/
  grep -r "import.*nombre-archivo-antiguo" apps/
  
  # Debe devolver 0 matches
  

• Actualizar configuraciones

  • tsconfig paths (si aplica)
  • Jest config (mocks, setup files)
  • ESLint ignores
  • Webpack/Vite aliases

2.2 Commits Incrementales

• Hacer commits pequeños y frecuentes

  git add .
  git commit -m "refactor: move {file} to {new-location}"
  git commit -m "refactor: update imports in {module}"
  git commit -m "refactor: update tests"
  

  • Commits atómicos (un tipo de cambio por commit)
  • Mensajes descriptivos

---

FASE 3: POST-REFACTORIZACIÓN (Validación)

3.1 Validación de Código

• Verificar compilación

  npm run type-check  # TypeScript check
  npm run build       # Build completo
  

  • ✅ 0 TypeScript errors
  • ✅ Build exitoso

• Ejecutar linter

  npm run lint
  

  • ✅ 0 lint errors
  • Resolver warnings si son relevantes

• Ejecutar tests

  npm run test           # Unit tests
  npm run test:e2e       # E2E tests (si aplica)
  npm run test:coverage  # Coverage (si aplica)
  

  • ✅ TODOS los tests pasando
  • ✅ Sin regresiones en cobertura

3.2 Validación Funcional

• Iniciar servidor de desarrollo

  npm run dev
  

  • ✅ Servidor inicia sin errores
  • ✅ Sin warnings críticos en console

• Validar funcionalidad en browser

  • Abrir aplicación en browser
  • Verificar console (NO debe haber errores)
  • Navegar páginas afectadas
  • Probar funcionalidades relacionadas
  • Verificar que todo funciona como antes

• Validar hot reload / HMR

  • Hacer cambio menor en archivo refactorizado
  • Verificar que hot reload funciona
  • Sin errores en console

3.3 Validación de Búsquedas

• Verificar NO quedan referencias al código antiguo

  # Buscar nombre de archivo antiguo
  grep -r "nombre-archivo-antiguo" apps/
  
  # Buscar ruta antigua
  grep -r "ruta/antigua" apps/
  
  # Debe devolver 0 matches (o solo comentarios/docs)
  

• Verificar imports correctos

  # Buscar nuevo path
  grep -r "nueva/ruta" apps/
  
  # Verificar que todos usan nueva ruta
  

3.4 Limpieza

• Eliminar archivos antiguos

  git rm ruta/antigua/archivo-antiguo.ts
  

  • Solo después de confirmar que NADA lo usa

• Eliminar código comentado (dead code)

  • NO dejar código antiguo comentado "por las dudas"
  • Git history mantiene el código si se necesita después

• Eliminar imports no usados

  • ESLint debería detectarlos
  • Usar herramienta del IDE para organizar imports

---

FASE 4: DOCUMENTACIÓN

4.1 Actualizar Documentación

• Actualizar documentación afectada

  • README.md (si aplica)
  • docs/architecture/ (si cambió arquitectura)
  • docs/97-adr/ (crear ADR si decisión arquitectónica)
  • orchestration/inventarios/ (si cambió inventario)

• Documentar cambios en CHANGELOG

  • Tipo de cambio (refactor)
  • Qué se movió/cambió
  • Impacto en otros desarrolladores

• Actualizar comentarios de código

  • Actualizar JSDoc si paths cambiaron
  • Actualizar ejemplos en comentarios

4.2 Crear Traza

• Crear reporte de refactorización
  • Ubicación: orchestration/agentes/{agente}/refactor-{nombre}-{fecha}/REPORTE.md
  • Incluir:
    • Objetivo de la refactorización
    • Archivos modificados
    • Validaciones realizadas
    • Problemas encontrados y soluciones
    • Lecciones aprendidas

---

FASE 5: CODE REVIEW

5.1 Preparación para PR

• Self-review

  • Revisar TODOS los cambios en diff
  • Verificar que NO hay cambios no relacionados
  • Verificar que NO hay console.logs olvidados
  • Verificar formateo consistente

• Crear PR con contexto completo

  ## Tipo de Cambio
  - [ ] Refactorización
  
  ## Objetivo
  {Descripción clara del objetivo de la refactorización}
  
  ## Cambios Principales
  - Movido {archivo A} → {ubicación B}
  - Actualizado {N} imports en {módulos}
  - ...
  
  ## Archivos Afectados
  - {número} archivos modificados
  - {número} archivos movidos
  - {número} archivos eliminados
  
  ## Validaciones Realizadas
  - ✅ Build exitoso
  - ✅ Tests pasando (X/X)
  - ✅ Servidor inicia correctamente
  - ✅ Funcionalidad validada en browser
  - ✅ 0 imports rotos
  
  ## Checklist de Refactorización
  - ✅ Pre-refactorización completada
  - ✅ Durante refactorización completada
  - ✅ Post-refactorización completada
  - ✅ Documentación actualizada
  

5.2 Responder a Code Review

• Atender comentarios de reviewers

  • Responder TODOS los comentarios
  • Implementar cambios solicitados
  • Re-validar después de cambios

• Re-ejecutar validaciones después de cambios

  • Build, tests, servidor funcionando
  • No romper lo que ya funcionaba

---

FASE 6: DEPLOYMENT

6.1 Pre-merge

• Merge/rebase con main/master

  git checkout main
  git pull
  git checkout refactor/nombre-descriptivo
  git rebase main  # o merge, según política del proyecto
  

• Resolver conflictos (si los hay)

  • Resolver con cuidado
  • Re-ejecutar TODAS las validaciones después de resolver

• Validación final

  npm run build
  npm run test
  npm run dev
  

  • ✅ Todo funciona después de merge/rebase

6.2 Post-merge

• Merge a main/master

  • Usar squash merge si muchos commits pequeños
  • O mantener commits si son significativos

• Validar en CI/CD

  • Esperar que pipeline pase
  • Si falla, investigar inmediatamente

• Monitorear después del merge

  • Revisar logs de errores
  • Monitorear alerts/monitoring
  • Estar disponible para hotfixes

---

🚨 SIGNALS DE ALERTA

Cuando DETENER y Re-planificar

• 🚨 Refactorización toma >2x el tiempo estimado → Pausar, re-evaluar estrategia

• 🚨 Encontraste >10 archivos no planeados que dependen del código → Pausar, actualizar plan

• 🚨 Tests empiezan a fallar en módulos no relacionados → Rollback, investigar

• 🚨 Build roto después de múltiples intentos → Rollback, pedir ayuda

---

📊 MÉTRICAS DE ÉXITO

Refactorización Exitosa

• ✅ 0 imports rotos
• ✅ 0 regresiones funcionales
• ✅ 100% tests pasando
• ✅ Build exitoso en < mismo tiempo que antes
• ✅ Código más limpio/mantenible que antes

Refactorización Fallida (Requiere Mejora)

• ❌ Imports rotos encontrados después de merge
• ❌ Bugs introducidos por la refactorización
• ❌ Tests fallando
• ❌ Performance degradada

---

🔧 HERRAMIENTAS ÚTILES

Búsqueda Global

# Encontrar TODAS las referencias
grep -r "nombre-busqueda" apps/
rg "nombre-busqueda" apps/  # (ripgrep, más rápido)

# Con contexto (3 líneas antes/después)
grep -r -C 3 "nombre-busqueda" apps/

# Solo nombres de archivo
grep -r -l "nombre-busqueda" apps/

# Excluir node_modules, dist, build
grep -r "nombre-busqueda" apps/ --exclude-dir={node_modules,dist,build}

Refactorización en IDE

VS Code:

• F2 → Rename symbol (actualiza imports automáticamente)
• Ctrl+Shift+H → Find and replace in files
• Command Palette → "Organize Imports"

WebStorm:

• Shift+F6 → Rename
• Ctrl+Alt+Shift+T → Refactor menu
• Ctrl+Alt+O → Optimize imports

Git

# Ver archivos modificados
git status

# Ver diff detallado
git diff

# Commit parcial (stage por partes)
git add -p

# Revert cambio específico
git checkout -- ruta/archivo.ts

---

📚 REFERENCIAS

Documentos Relacionados

• Directiva de Calidad de Código
• Estándares de Nomenclatura
• Documentación Obligatoria
• Frontend API Architecture

Ejemplos de Refactorizaciones

• BUG-FRONTEND-001 - Imports rotos por refactorización incompleta
• BUG-FRONTEND-002 - Rutas hard-coded incorrectas

---

✅ RESUMEN: GOLDEN RULES

1. NUNCA elimines un archivo sin verificar que NADA lo usa
2. SIEMPRE actualiza TODOS los imports (usa búsqueda global)
3. SIEMPRE valida que servidor/tests funcionan DESPUÉS del cambio
4. NUNCA hagas múltiples refactorizaciones en el mismo PR
5. SIEMPRE documenta en CHANGELOG/traza lo que hiciste
6. SIEMPRE haz commits pequeños y frecuentes
7. NUNCA merges código que no has validado localmente
8. SIEMPRE pide code review para refactorizaciones no triviales

---

Versión: 1.0.0 Última actualización: 2025-11-23 Estado: Directiva Obligatoria Proyecto: GAMILIT Mantenido por: Architecture Team