theus-cli-darwin-x64 0.2.84

package/vendor/theus-arsenal/commands/prp-implementar.md

@@ -0,0 +1,385 @@
+---
+description: "Ejecuta un plan de implementación con bucles de validación rigurosos — parte de la serie PRP."
+argument-hint: "<ruta/al/plan.md>"
+---
+
+# PRP Implementar
+
+Parte de la serie de flujos PRP (planificar → implementar → commit).
+
+Ejecuta un archivo de plan paso a paso con validación continua. Cada cambio se verifica de inmediato — nunca acumules estado roto.
+
+**Filosofía central**: los bucles de validación atrapan los errores temprano. Ejecuta las verificaciones tras cada cambio. Corrige los problemas de inmediato.
+
+**Regla de oro**: si una validación falla, arréglala antes de seguir. Nunca acumules estado roto.
+
+---
+
+## Fase 0 — DETECTAR
+
+### Detección del gestor de paquetes
+
+| Archivo presente | Gestor de paquetes | Ejecutor |
+|---|---|---|
+| `bun.lockb` | bun | `bun run` |
+| `pnpm-lock.yaml` | pnpm | `pnpm run` |
+| `yarn.lock` | yarn | `yarn` |
+| `package-lock.json` | npm | `npm run` |
+| `pyproject.toml` o `requirements.txt` | uv / pip | `uv run` o `python -m` |
+| `Cargo.toml` | cargo | `cargo` |
+| `go.mod` | go | `go` |
+
+### Scripts de validación
+
+Revisa `package.json` (o equivalente) en busca de scripts disponibles:
+
+```bash
+# Para proyectos Node.js
+cat package.json | grep -A 20 '"scripts"'
+```
+
+Anota los comandos disponibles para: verificación de tipos, lint, tests y build.
+
+---
+
+## Fase 1 — CARGAR
+
+Lee el archivo del plan:
+
+```bash
+cat "$ARGUMENTS"
+```
+
+Extrae estas secciones del plan:
+- **Resumen** — qué se construye
+- **Patrones a imitar** — convenciones de código a seguir
+- **Archivos a cambiar** — qué crear o modificar
+- **Tareas paso a paso** — secuencia de implementación
+- **Comandos de validación** — cómo verificar la corrección
+- **Criterios de aceptación** — definición de terminado
+
+Si el archivo no existe o no es un plan válido:
+```
+Error: archivo de plan no encontrado o inválido.
+Ejecuta /prp-planificar <descripción-de-la-funcionalidad> para crear un plan primero.
+```
+
+**PUNTO DE CONTROL**: plan cargado. Todas las secciones identificadas. Tareas extraídas.
+
+---
+
+## Fase 2 — PREPARAR
+
+### Estado de git
+
+```bash
+git branch --show-current
+git status --porcelain
+```
+
+### Decisión de rama
+
+| Estado actual | Acción |
+|---|---|
+| En una rama de funcionalidad | Usar la rama actual |
+| En main, árbol de trabajo limpio | Crear rama de funcionalidad: `git checkout -b feat/{nombre-del-plan}` |
+| En main, árbol de trabajo sucio | **DETENERSE** — pedir al usuario que haga stash o commit primero |
+| En un worktree de git para esta funcionalidad | Usar el worktree |
+
+### Sincronizar con el remoto
+
+```bash
+git pull --rebase origin $(git branch --show-current) 2>/dev/null || true
+```
+
+**PUNTO DE CONTROL**: en la rama correcta. Árbol de trabajo listo. Remoto sincronizado.
+
+---
+
+## Fase 3 — EJECUTAR
+
+Procesa cada tarea del plan de forma secuencial.
+
+### Bucle por tarea
+
+Para cada tarea en **Tareas paso a paso**:
+
+1. **Leer la referencia IMITAR** — Abre el archivo de patrón referenciado en el campo IMITAR de la tarea. Entiende la convención antes de escribir código.
+
+2. **Implementar** — Escribe el código siguiendo el patrón al pie de la letra. Aplica las advertencias TRAMPA. Usa los IMPORTS especificados.
+
+3. **Validar de inmediato** — Tras CADA cambio de archivo:
+   ```bash
+   # Ejecutar verificación de tipos (ajusta el comando según el proyecto)
+   [comando de verificación de tipos de la Fase 0]
+   ```
+   Si la verificación de tipos falla → corrige el error antes de pasar al siguiente archivo.
+
+4. **Registrar progreso** — Anota: `[hecho] Tarea N: [nombre de la tarea] — completada`
+
+### Manejo de desviaciones
+
+Si la implementación debe desviarse del plan:
+- Anota **QUÉ** cambió
+- Anota **POR QUÉ** cambió
+- Continúa con el enfoque corregido
+- Estas desviaciones se capturarán en el informe
+
+**PUNTO DE CONTROL**: todas las tareas ejecutadas. Desviaciones registradas.
+
+---
+
+## Fase 4 — VALIDAR
+
+Ejecuta todos los niveles de validación del plan. Corrige los problemas de cada nivel antes de continuar.
+
+### Nivel 1: análisis estático
+
+```bash
+# Verificación de tipos — se exigen cero errores
+[comando de verificación de tipos del proyecto]
+
+# Lint — corregir automáticamente donde sea posible
+[comando de lint del proyecto]
+[comando de lint con auto-corrección del proyecto]
+```
+
+Si quedan errores de lint tras la auto-corrección, corrígelos manualmente.
+
+### Nivel 2: tests unitarios
+
+Escribe tests para cada función nueva (según la Estrategia de testing del plan).
+
+```bash
+[comando de tests del proyecto para el área afectada]
+```
+
+- Cada función necesita al menos un test
+- Cubre los casos límite listados en el plan
+- Si un test falla → corrige la implementación (no el test, salvo que el test sea el que está mal)
+
+### Nivel 3: verificación de build
+
+```bash
+[comando de build del proyecto]
+```
+
+El build debe completarse con cero errores.
+
+### Nivel 4: tests de integración (si aplica)
+
+```bash
+# Levantar el servidor, ejecutar los tests, detener el servidor
+[comando de servidor de desarrollo del proyecto] &
+SERVER_PID=$!
+
+# Esperar a que el servidor esté listo (ajusta el puerto según corresponda)
+SERVER_READY=0
+for i in $(seq 1 30); do
+  if curl -sf http://localhost:PUERTO/health >/dev/null 2>&1; then
+    SERVER_READY=1
+    break
+  fi
+  sleep 1
+done
+
+if [ "$SERVER_READY" -ne 1 ]; then
+  kill "$SERVER_PID" 2>/dev/null || true
+  echo "ERROR: el servidor no arrancó en 30s" >&2
+  exit 1
+fi
+
+[comando de tests de integración]
+TEST_EXIT=$?
+
+kill "$SERVER_PID" 2>/dev/null || true
+wait "$SERVER_PID" 2>/dev/null || true
+
+exit "$TEST_EXIT"
+```
+
+### Nivel 5: tests de casos límite
+
+Recorre los casos límite del checklist de la Estrategia de testing del plan.
+
+**PUNTO DE CONTROL**: los 5 niveles de validación pasan. Cero errores.
+
+---
+
+## Fase 5 — INFORMAR
+
+### Crear el informe de implementación
+
+```bash
+mkdir -p .theus/prp/informes
+```
+
+Escribe el informe en `.theus/prp/informes/{nombre-del-plan}-informe.md`:
+
+```markdown
+# Informe de implementación: [Nombre de la funcionalidad]
+
+## Resumen
+[Qué se implementó]
+
+## Estimación vs. realidad
+
+| Métrica | Previsto (plan) | Real |
+|---|---|---|
+| Complejidad | [del plan] | [real] |
+| Confianza | [del plan] | [real] |
+| Archivos cambiados | [del plan] | [cantidad real] |
+
+## Tareas completadas
+
+| # | Tarea | Estado | Notas |
+|---|---|---|---|
+| 1 | [nombre de la tarea] | [hecho] Completada | |
+| 2 | [nombre de la tarea] | [hecho] Completada | Con desviación — [motivo] |
+
+## Resultados de validación
+
+| Nivel | Estado | Notas |
+|---|---|---|
+| Análisis estático | [hecho] Pasa | |
+| Tests unitarios | [hecho] Pasa | N tests escritos |
+| Build | [hecho] Pasa | |
+| Integración | [hecho] Pasa | o N/A |
+| Casos límite | [hecho] Pasa | |
+
+## Archivos cambiados
+
+| Archivo | Acción | Líneas |
+|---|---|---|
+| `ruta/al/archivo` | CREADO | +N |
+| `ruta/al/archivo` | ACTUALIZADO | +N / -M |
+
+## Desviaciones respecto al plan
+[Lista de desviaciones con QUÉ y POR QUÉ, o "Ninguna"]
+
+## Problemas encontrados
+[Lista de problemas y cómo se resolvieron, o "Ninguno"]
+
+## Tests escritos
+
+| Archivo de test | Tests | Cobertura |
+|---|---|---|
+| `ruta/al/test` | N tests | [área cubierta] |
+
+## Siguientes pasos
+- [ ] Revisión de código con `/revisar-codigo`
+- [ ] Crear PR con `/pr`
+```
+
+### Actualizar el PRD (si aplica)
+
+Si esta implementación correspondía a una fase de un PRD:
+1. Actualiza el estado de la fase de `en-progreso` a `completa`
+2. Añade la ruta del informe como referencia
+
+### Archivar el plan
+
+```bash
+mkdir -p .theus/prp/planes/completados
+mv "$ARGUMENTS" .theus/prp/planes/completados/
+```
+
+**PUNTO DE CONTROL**: informe creado. PRD actualizado. Plan archivado.
+
+---
+
+## Fase 6 — SALIDA
+
+Informe al usuario:
+
+```
+## Implementación completada
+
+- **Plan**: [ruta del plan] → archivado en completados/
+- **Rama**: [nombre de la rama actual]
+- **Estado**: [hecho] Todas las tareas completadas
+
+### Resumen de validación
+
+| Verificación | Estado |
+|---|---|
+| Tipos | [hecho] |
+| Lint | [hecho] |
+| Tests | [hecho] (N escritos) |
+| Build | [hecho] |
+| Integración | [hecho] o N/A |
+
+### Archivos cambiados
+- [N] archivos creados, [M] archivos actualizados
+
+### Desviaciones
+[Resumen o "Ninguna — implementado exactamente según el plan"]
+
+### Artefactos
+- Informe: `.theus/prp/informes/{nombre}-informe.md`
+- Plan archivado: `.theus/prp/planes/completados/{nombre}.plan.md`
+
+### Progreso del PRD (si aplica)
+| Fase | Estado |
+|---|---|
+| Fase 1 | [hecho] Completa |
+| Fase 2 | [siguiente] |
+| ... | ... |
+
+> Siguiente paso: ejecuta `/pr` para crear un pull request, o `/revisar-codigo` para revisar los cambios antes.
+```
+
+---
+
+## Manejo de fallos
+
+### Falla la verificación de tipos
+1. Lee el mensaje de error con atención
+2. Corrige el error de tipos en el archivo fuente
+3. Vuelve a ejecutar la verificación
+4. Continúa solo cuando esté limpio
+
+### Fallan los tests
+1. Determina si el error está en la implementación o en el test
+2. Corrige la causa raíz (normalmente la implementación)
+3. Vuelve a ejecutar los tests
+4. Continúa solo cuando estén en verde
+
+### Falla el lint
+1. Ejecuta primero la auto-corrección
+2. Si quedan errores, corrígelos manualmente
+3. Vuelve a ejecutar el lint
+4. Continúa solo cuando esté limpio
+
+### Falla el build
+1. Suele ser un problema de tipos o de imports — revisa el mensaje de error
+2. Corrige el archivo problemático
+3. Vuelve a ejecutar el build
+4. Continúa solo cuando termine con éxito
+
+### Fallan los tests de integración
+1. Verifica que el servidor arrancó correctamente
+2. Comprueba que el endpoint/ruta existe
+3. Verifica que el formato de la petición coincide con lo esperado
+4. Corrige y vuelve a ejecutar
+
+---
+
+## Criterios de éxito
+
+- **TAREAS_COMPLETAS**: todas las tareas del plan ejecutadas
+- **TIPOS_OK**: cero errores de tipos
+- **LINT_OK**: cero errores de lint
+- **TESTS_OK**: todos los tests en verde, tests nuevos escritos
+- **BUILD_OK**: el build termina con éxito
+- **INFORME_CREADO**: informe de implementación guardado
+- **PLAN_ARCHIVADO**: plan movido a `completados/`
+
+---
+
+## Siguientes pasos
+
+- Ejecuta `/revisar-codigo` para revisar los cambios antes de commitear
+- Ejecuta `/prp-commit` para commitear con un mensaje descriptivo
+- Ejecuta `/pr` para crear un pull request
+- Ejecuta `/prp-planificar <siguiente-fase>` si el PRD tiene más fases