wicttor/pwrl

PWRL Plan — Orquestador de Skills Puro

Crea planes de implementación duraderos que se puedan delegar para su ejecución. Orquesta un pipeline determinista de micro-skills: alcance → investigación → diseño → generar. Sin dependencia de agente, sin rutas de respaldo.

Propósito

Los planes capturan decisiones, estructura y enfoque antes de la ejecución. Permiten:

• Alcance claro y criterios de éxito
• Riesgos y dependencias identificados
• Unidades de implementación concretas con criterios de aceptación
• Reutilización del conocimiento a través de aprendizajes relacionados
• Confianza de que el trabajo no se desviará

Flujo de Trabajo Principal: Pipeline de Cuatro Fases

ENTRADA (descripción de la tarea)
  ↓
FASE 1: Alcance (pwrl-plan-scope)
  → Recopilar contexto, validar dominio, iniciar requisitos
  → Salida: Artefacto de contexto con alcance
  ↓
FASE 2: Investigación (pwrl-plan-research)
  → Descubrir patrones, identificar riesgos, recomendar investigación externa
  → Salida: Artefacto de hallazgos de investigación
  ↓
FASE 3: Diseño (pwrl-plan-design)
  → Descomponer en unidades, mapear dependencias, evaluar complejidad
  → Salida: Artefacto de diseño con descomposición de unidades
  ↓
FASE 4: Generar (pwrl-plan-generate)
  → Seleccionar nivel, renderizar plan, incrustar aprendizajes, guardar en docs/plans/
  → Salida: Documento de plan final guardado en archivo
  ↓
SALIDA (archivo de plan listo para ejecución)

Detalles de las Fases

Fase 1: Alcance (pwrl-plan-scope)

Propósito: Punto de entrada al flujo de planificación. Recopila contexto, verifica planes existentes y aprendizajes, valida el dominio y devuelve un objeto de contexto con alcance.

Micro-Skill: pwrl-plan-scope

Entrada:

• El usuario proporciona una descripción de la tarea, documento de requisitos u objetivo
• Entrada vacía solicita al usuario: "¿Qué te gustaría planificar?"

Procesamiento:

1. Verificar planes existentes en docs/plans/; sugerir reanudar/revisar/archivar/eliminar/nuevo
2. Validar dominio (software vs. no software)
3. Iniciar marco del problema, comportamiento esperado, criterios de éxito
4. Buscar aprendizajes relacionados en docs/learnings/INDEX.md
5. Buscar documentos coincidentes en docs/requirements/ y docs/brainstorms/
6. Confirmar contexto con el usuario
7. Preguntar modo de interacción:
   • Detallado: Interacción paso a paso en cada fase (revisar, confirmar, ajustar)
   • Yolo: Automatización completa desde la Fase 1 hasta la Fase 4, solo confirmación final
8. Generar artefacto de alcance con modo de interacción

Salida: Artefacto de contexto con alcance que incluye:

• Marco del problema, comportamiento esperado, criterios de éxito
• Aprendizajes relacionados (relevancia ALTA)
• Brechas de aprendizaje identificadas
• Requisitos encontrados
• modo_interacción (detallado o yolo)

Ver: pwrl-plan-scope/SKILL.md para el flujo de trabajo detallado

Fase 2: Investigación (pwrl-plan-research)

Propósito: Descubrir patrones locales, pila tecnológica y áreas de alto riesgo. Recomendar investigación externa si es necesario.

Micro-Skill: pwrl-plan-research

Entrada: Artefacto de contexto con alcance de la Fase 1

Procesamiento:

1. Detectar pila tecnológica desde package.json, Dockerfile, estructura del código base
2. Descubrir patrones locales (arquitectura, estilo asíncrono, pruebas, organización)
3. Identificar áreas de alto riesgo (seguridad, rendimiento, migraciones, sistemas distribuidos, cumplimiento)
4. Recomendar investigación externa para áreas de alto riesgo (opcional)
5. Integrar conocimientos de aprendizajes relacionados
6. Compilar hallazgos de investigación

Salida: Artefacto de investigación con:

• Detección de pila tecnológica
• Patrones locales identificados
• Áreas de riesgo con recomendaciones
• Hallazgos de investigación externa (si se realizó)
• Notas de integración de aprendizajes

Ver: pwrl-plan-research/SKILL.md para el flujo de trabajo detallado

Fase 3: Diseño (pwrl-plan-design)

Propósito: Descomponer el trabajo en unidades de implementación, identificar dependencias y riesgos, evaluar complejidad.

Micro-Skill: pwrl-plan-design

Entrada: Contexto con alcance + Hallazgos de investigación

Procesamiento:

1. Identificar unidades de trabajo a partir de criterios de éxito y áreas de riesgo
2. Mapear dependencias entre unidades (orden topológico)
3. Detectar dependencias circulares; solicitar refactorización
4. Crear unidades de mitigación de riesgos
5. Generar diagramas Mermaid para flujos de trabajo complejos (5+ unidades)
6. Evaluar complejidad (BAJA/MEDIA/ALTA)
7. Estimar esfuerzo
8. Confirmar descomposición con el usuario

Salida: Artefacto de diseño con:

• Unidades de implementación (U1, U2, ..., UX) con escenarios de prueba y criterios de aceptación
• Grafo de dependencias y orden topológico
• Mitigaciones de riesgos
• Diagramas Mermaid (si es complejo)
• Evaluación de complejidad y estimación de esfuerzo

Ver: pwrl-plan-design/SKILL.md para el flujo de trabajo detallado

Fase 4: Generar (pwrl-plan-generate)

Propósito: Seleccionar nivel (Rápido/Estándar/Profundo), renderizar plan usando la plantilla del nivel, incrustar aprendizajes, guardar en docs/plans/.

Micro-Skill: pwrl-plan-generate

Entrada: Artefacto de diseño (de la Fase 3) + Artefacto de alcance (de la Fase 1)

Procesamiento:

1. Seleccionar automáticamente el nivel según complejidad/unidades/esfuerzo; solicitar si es ambiguo
   • RÁPIDO: Complejidad BAJA, 1-3 unidades, <5 horas
   • ESTÁNDAR: Complejidad MEDIA, 4-8 unidades, 5-20 horas
   • PROFUNDO: Complejidad ALTA, 9+ unidades, 20+ horas
2. Renderizar plan usando la plantilla específica del nivel
3. Incrustar los 3-5 aprendizajes de mayor relevancia del alcance
4. Generar nombre de archivo único: YYYY-MM-DD-NNN-<slug>.md
5. Manejar colisiones de nombres de archivo (incrementar secuencia o actualizar existente)
6. Guardar plan en docs/plans/

Salida: Documento de plan guardado en archivo con:

• Problema y alcance
• Criterios de éxito
• Unidades de implementación (nivel de detalle específico del nivel)
• Análisis de riesgos (ESTÁNDAR/PROFUNDO)
• Aprendizajes relacionados (ESTÁNDAR/PROFUNDO)
• Brechas de aprendizaje (PROFUNDO)
• Notas de despliegue (ESTÁNDAR/PROFUNDO)

Ver: pwrl-plan-generate/SKILL.md para el flujo de trabajo detallado

Niveles de Planificación

Nivel	Mejor Para	Archivos	Riesgo	Tiempo
RÁPIDO	Correcciones de errores, ajustes pequeños	1-3	BAJO	5-15 min
ESTÁNDAR	La mayoría de las funciones	4-8	MED	30-45 min
PROFUNDO	Arquitectura, seguridad, migraciones	9+	ALTO	1-2 horas

Ver references/planning-tiers.md para los criterios completos de decisión de niveles y ejemplos de plantillas.

Principios Fundamentales

• Pipeline Determinista: Las fases siempre se ejecutan en secuencia: alcance → investigación → diseño → generar (sin bifurcaciones, sin respaldo)
• Enfoque en Decisiones: Capturar enfoque, estructura, riesgos y secuenciación (no simulación de código)
• Tamaño Adecuado: Tareas pequeñas → planes cortos; trabajo complejo → más estructura
• Separar Planificación de Ejecución: No simular la implementación durante la planificación
• Ser Concreto: Usar archivos, componentes y dependencias específicos
• Mantenerse Portable: Usar solo rutas relativas al repositorio
• Artefactos Transparentes: Cada fase produce un artefacto de salida explícito para la siguiente fase

Manejo de Errores y Recuperación

Filosofía: Fallar explícitamente, no en silencio. Cada fase tiene un manejo de errores claro con sugerencias de recuperación.

Errores de la Fase 1 (Alcance)

• Entrada Vacía: Solicitar al usuario una descripción de la tarea; reintentar
• Dominio No Software: Devolver error; sugerir herramienta alternativa
• Entrada Ambigua: Hacer preguntas aclaratorias; iniciar con respuestas del usuario
• Sin Aprendizajes/Requisitos: Continuar (no es un error)

Recuperación: El usuario puede reintentar, proporcionar aclaración o cancelar

Errores de la Fase 2 (Investigación)

• Fallo en Análisis del Código Base: Continuar con información mínima de la pila tecnológica
• Área de Alto Riesgo Identificada: Recomendar investigación externa; el usuario puede aprobar u omitir

Recuperación: El usuario puede aprobar la investigación, omitirla o investigar manualmente

Errores de la Fase 3 (Diseño)

• Dependencia Circular Detectada: Informar la ruta del ciclo; solicitar al usuario refactorizar
• Demasiadas Unidades (15+): Advertir sobre la complejidad; sugerir consolidación
• Detalle Insuficiente: Solicitar agregar escenarios de prueba o dividir unidades

Recuperación: El usuario puede refactorizar, consolidar o continuar con conocimiento

Errores de la Fase 4 (Generar)

• Colisión de Nombre de Archivo: Ofrecer opciones: actualizar, incrementar o cancelar
• Selección de Nivel Ambiguo: Solicitar al usuario elegir el nivel
• Fallo en Escritura de Archivo: Verificar permisos/directorio; reintentar o sugerir guardado manual

Recuperación: El usuario puede elegir una acción o guardar manualmente

Salidas Clave

Cada plan incluye (dependiendo del nivel):

• Problema y Alcance: Marco claro del problema y comportamiento esperado
• Criterios de Éxito: 1-3 condiciones específicas para la finalización
• Unidades de Implementación: U-ID con nombre, dependencias, archivos, enfoque y criterios de aceptación
• Aprendizajes Relacionados: Archivos de aprendizaje vinculados con notas de aplicabilidad (ESTÁNDAR/PROFUNDO)
• Brechas de Aprendizaje: Áreas que necesitan documentación posterior a la implementación (PROFUNDO)
• Secciones Específicas del Nivel: Análisis de riesgos, alternativas, notas de despliegue (ESTÁNDAR/PROFUNDO)

Método de Interacción

• Usar la extensión ask_user_questions de la plataforma para todas las decisiones
• Hacer una pregunta a la vez
• Usar preguntas de opción múltiple cuando sea posible
• Si la entrada está vacía, preguntar: "¿Qué te gustaría planificar? Describe la tarea o el proyecto."
• Proporcionar sugerencias de recuperación claras cuando ocurran errores

Arquitectura: Sin Enrutamiento de Agente

Diferencia con la Versión Anterior:

Antes: El skill detectaba si el agente estaba disponible, luego delegaba al agente O ejecutaba un respaldo monolítico (dos rutas de código)

Después: El skill llama directamente a los micro-skills en secuencia—un único pipeline determinista, sin bifurcaciones:

orquestador pwrl-plan
├── 1. Llamar a pwrl-plan-scope → obtener artefacto de alcance
├── 2. Llamar a pwrl-plan-research → obtener artefacto de investigación
├── 3. Llamar a pwrl-plan-design → obtener artefacto de diseño
└── 4. Llamar a pwrl-plan-generate → guardar archivo de plan

Beneficios:

• ✅ Más simple de entender (ruta de código única)
• ✅ Más fácil de probar (sin lógica de bifurcación)
• ✅ Más mantenible (micro-skills probables de forma independiente)
• ✅ Más componible (micro-skills reutilizables en otros flujos de trabajo)
• ✅ Mejor manejo de errores (explícito en cada fase)

Referencias de Micro-Skills

• pwrl-plan-scope — Recopilación de contexto y alcance
• pwrl-plan-research — Descubrimiento de patrones e identificación de riesgos
• pwrl-plan-design — Descomposición de unidades y mapeo de dependencias
• pwrl-plan-generate — Renderizado de plan y generación de archivos

Documentación Relacionada

• references/planning-tiers.md — Definiciones de niveles y criterios de decisión
• docs/guides/micro-skill-patterns.md — Cómo extender con nuevos micro-skills
• docs/guides/skill-architecture-refactoring.md — Justificación de la refactorización

Pruebas y Validación

Cobertura de pruebas completa:

• 30+ pruebas para pwrl-plan-scope (U1.1)
• 25+ pruebas para pwrl-plan-research (U1.2)
• 35+ pruebas para pwrl-plan-design (U1.3)
• 30+ pruebas para pwrl-plan-generate (U1.4)
• 30+ pruebas de integración para el pipeline completo de orquestación

Compatibilidad hacia atrás:

• Mismo comportamiento de entrada/salida que la versión anterior
• Planes existentes generados con éxito
• Sin cambios disruptivos para los usuarios

Preguntas Frecuentes

P: ¿Qué pasa si una fase falla? ¿Puedo saltármela o reintentar?

R: Sí. Cada fase tiene un manejo de errores explícito con sugerencias de recuperación. Puedes reintentar, proporcionar aclaración, modificar el alcance o cancelar. Sin fallos silenciosos.

P: ¿Puedo usar solo un micro-skill (por ejemplo, solo generar desde diseño)?

R: El orquestador espera llamar a las cuatro fases en secuencia. Si deseas usar un solo micro-skill, llámalo directamente por su nombre: /pwrl-plan-scope, /pwrl-plan-design, etc.

P: ¿Por qué no hay enrutamiento de agente?

R: Los agentes añadían complejidad sin valor. El pipeline de micro-skills es determinista, comprobable y más fácil de entender. La llamada directa a skills es más simple y mantenible.

P: ¿Puedo extender esto para otros flujos de trabajo?

R: ¡Sí! Los micro-skills son reutilizables. Por ejemplo, pwrl-work puede usar pwrl-plan-design para la descomposición de unidades. Ver docs/guides/micro-skill-patterns.md.

---

Estado: Pipeline de skills puro (sin enrutamiento de agente) Versión: 2.0 (refactorizado desde arquitectura dependiente de agente) Creado: 2026-06-11