Ralph TUI - Crear Tareas JSON
Convierte PRDs al formato prd.json para la ejecución autónoma con ralph-tui.
Nota: Este skill está incluido con el plugin de seguimiento JSON de ralph-tui. Los futuros plugins de seguimiento (Linear, GitHub Issues, etc.) incluirán sus propios skills de creación de tareas.
⚠️ CRÍTICO: La salida DEBE ser un objeto JSON PLANO con "name" y "userStories" al NIVEL RAÍZ. NO envuelvas el contenido en un objeto "prd" ni uses un arreglo "tasks". Consulta la sección "Antipatrones de Esquema" más abajo.
El Trabajo
Toma un PRD (archivo markdown o texto) y crea un archivo prd.json:
- Extraer las Puertas de Calidad de la sección "Puertas de Calidad" del PRD
- Analizar las historias de usuario del PRD
- Añadir las puertas de calidad a los criterios de aceptación de cada historia
- Configurar dependencias entre historias
- Generar la salida lista para
ralph-tui run --prd <ruta>
Paso 1: Extraer Puertas de Calidad
Busca la sección "Puertas de Calidad" en el PRD:
## Puertas de Calidad
Estos comandos deben pasar para cada historia de usuario:
- `pnpm typecheck` - Verificación de tipos
- `pnpm lint` - Análisis de código
Para historias de UI, incluye también:
- Verificar en el navegador usando el skill dev-browser
Extrae:
- Puertas universales: Comandos que se aplican a TODAS las historias (p. ej.,
pnpm typecheck) - Puertas de UI: Comandos que se aplican solo a las historias de UI (p. ej., verificación en navegador)
Si no existe la sección "Puertas de Calidad": Pregunta al usuario qué comandos deben pasar, o usa un valor predeterminado sensato como npm run typecheck.
Formato de Salida
El archivo JSON DEBE ser un objeto PLANO a nivel raíz:
{
"name": "[Nombre del proyecto del PRD o del directorio]",
"branchName": "ralph/[nombre-de-funcionalidad-en-kebab-case]",
"description": "[Descripción de la funcionalidad del PRD]",
"userStories": [
{
"id": "US-001",
"title": "[Título de la historia]",
"description": "Como [usuario], quiero [funcionalidad] para [beneficio]",
"acceptanceCriteria": [
"Criterio 1 del PRD",
"Criterio 2 del PRD",
"pnpm typecheck pasa",
"pnpm lint pasa"
],
"priority": 1,
"passes": false,
"notes": "",
"dependsOn": []
},
{
"id": "US-002",
"title": "[Historia de UI que depende de US-001]",
"description": "...",
"acceptanceCriteria": [
"...",
"pnpm typecheck pasa",
"pnpm lint pasa",
"Verificar en el navegador usando el skill dev-browser"
],
"priority": 2,
"passes": false,
"notes": "",
"dependsOn": ["US-001"]
}
]
}
CRÍTICO: Antipatrones de Esquema (NO USAR)
Los siguientes patrones son INVÁLIDOS y causarán errores de validación:
❌ INCORRECTO: Objeto contenedor
{
"prd": {
"name": "...",
"userStories": [...]
}
}
Esto envuelve todo en un objeto "prd". NO HAGAS ESTO. Los campos "name" y "userStories" deben estar al NIVEL RAÍZ.
❌ INCORRECTO: Usar "tasks" en lugar de "userStories"
{
"name": "...",
"tasks": [...]
}
El arreglo se llama "userStories", no "tasks".
❌ INCORRECTO: Estructuras anidadas complejas
{
"metadata": {...},
"overview": {...},
"migration_strategy": {
"phases": [...]
}
}
Incluso si el PRD describe fases/hitos/sprints, DEBES aplanarlos en un solo arreglo "userStories".
❌ INCORRECTO: Usar "status" en lugar de "passes"
{
"userStories": [{
"id": "US-001",
"status": "open" // ¡INCORRECTO!
}]
}
Usa "passes": false para historias incompletas, "passes": true para completadas.
✅ CORRECTO: Estructura plana a nivel raíz
{
"name": "Migración a Kotlin en Android",
"branchName": "ralph/migracion-kotlin",
"userStories": [
{"id": "US-001", "title": "Crear interfaz Scraper", "passes": false, "dependsOn": []},
{"id": "US-002", "title": "Implementar WeebCentralScraper", "passes": false, "dependsOn": ["US-001"]}
]
}
Tamaño de las Historias: La Regla #1
Cada historia debe poder completarse en UNA iteración de ralph-tui (~una ventana de contexto del agente).
Ralph-tui crea una instancia de agente nueva por iteración sin memoria del trabajo anterior. Si una historia es demasiado grande, el agente se queda sin contexto antes de terminar.
Historias de tamaño adecuado:
- Añadir una columna a la base de datos + migración
- Añadir un componente de UI a una página existente
- Actualizar una server action con nueva lógica
- Añadir un menú desplegable de filtros a una lista
Demasiado grandes (dividir estas):
- "Construir todo el panel de control" → Dividir en: esquema, consultas, componentes de UI, filtros
- "Añadir autenticación" → Dividir en: esquema, middleware, UI de inicio de sesión, manejo de sesiones
- "Refactorizar la API" → Dividir en una historia por endpoint o patrón
Regla general: Si no puedes describir el cambio en 2-3 oraciones, es demasiado grande.
Dependencias con dependsOn
Usa el arreglo dependsOn para especificar qué historias deben completarse primero:
{
"id": "US-002",
"title": "Crear endpoints de API",
"dependsOn": ["US-001"], // No se seleccionará hasta que US-001 pase
...
}
Ralph-tui:
- Mostrará US-002 como "bloqueada" hasta que US-001 se complete
- Nunca seleccionará US-002 para ejecución mientras US-001 esté abierta
- Incluirá "Prerrequisitos: US-001" en el prompt al trabajar en US-002
Orden de dependencia correcto:
- Cambios de esquema/base de datos (sin dependencias)
- Lógica de backend (depende del esquema)
- Componentes de UI (dependen del backend)
- Integración/pulido (depende de la UI)
Criterios de Aceptación: Puertas de Calidad + Específicos de la Historia
Los criterios de aceptación de cada historia deben incluir:
- Criterios específicos de la historia del PRD (lo que logra esta historia)
- Puertas de calidad de la sección "Puertas de Calidad" del PRD (añadidas al final)
Buenos criterios (verificables):
- "Añadir columna
statusa la tabla tasks con valor predeterminado 'open'" - "El menú desplegable de filtros tiene opciones: Todas, Abiertas, Cerradas"
- "Hacer clic en eliminar muestra un diálogo de confirmación"
Malos criterios (vagos):
- ❌ "Funciona correctamente"
- ❌ "El usuario puede hacer X fácilmente"
- ❌ "Buena experiencia de usuario"
- ❌ "Maneja casos extremos"
Reglas de Conversión
- Extraer Puertas de Calidad del PRD primero
- Cada historia de usuario → una entrada JSON
- IDs: Secuenciales (US-001, US-002, etc.)
- Prioridad: Basada en el orden de dependencia (1 = más alta)
- dependsOn: Arreglo de IDs de historias que esta historia requiere
- Todas las historias:
passes: falseynotesvacío - branchName: Derivar del nombre de la funcionalidad, en kebab-case, con prefijo
ralph/ - Criterios de aceptación: Criterios de la historia + puertas de calidad añadidas
- Historias de UI: También añadir puertas específicas de UI (verificación en navegador)
Ubicación de Salida
Predeterminado: ./tasks/prd.json (junto a los archivos markdown del PRD)
Esto mantiene todos los archivos relacionados con el PRD juntos en el directorio tasks/.
O especifica una ruta diferente - ralph-tui la usará con:
ralph-tui run --prd ./ruta/a/prd.json
Ejemplo
PRD de entrada:
# PRD: Sistema de Prioridad de Tareas
Añadir niveles de prioridad a las tareas.
## Puertas de Calidad
Estos comandos deben pasar para cada historia de usuario:
- `pnpm typecheck` - Verificación de tipos
- `pnpm lint` - Análisis de código
Para historias de UI, incluye también:
- Verificar en el navegador usando el skill dev-browser
## Historias de Usuario
### US-001: Añadir campo de prioridad a la base de datos
**Descripción:** Como desarrollador, necesito almacenar la prioridad de las tareas.
**Criterios de Aceptación:**
- [ ] Añadir columna de prioridad: 1-4 (predeterminado 2)
- [ ] La migración se ejecuta correctamente
### US-002: Mostrar insignia de prioridad en tarjetas de tareas
**Descripción:** Como usuario, quiero ver la prioridad de la tarea de un vistazo.
**Criterios de Aceptación:**
- [ ] La insignia muestra P1/P2/P3/P4 con colores
- [ ] La insignia es visible sin pasar el ratón
### US-003: Añadir menú desplegable de filtro por prioridad
**Descripción:** Como usuario, quiero filtrar tareas por prioridad.
**Criterios de Aceptación:**
- [ ] Menú desplegable de filtro: Todas, P1, P2, P3, P4
- [ ] El filtro persiste en la URL
Salida prd.json:
{
"project": "mi-app",
"branchName": "ralph/prioridad-tareas",
"description": "Añadir niveles de prioridad a las tareas",
"userStories": [
{
"id": "US-001",
"title": "Añadir campo de prioridad a la base de datos",
"description": "Como desarrollador, necesito almacenar la prioridad de las tareas.",
"acceptanceCriteria": [
"Añadir columna de prioridad: 1-4 (predeterminado 2)",
"La migración se ejecuta correctamente",
"pnpm typecheck pasa",
"pnpm lint pasa"
],
"priority": 1,
"passes": false,
"notes": "",
"dependsOn": []
},
{
"id": "US-002",
"title": "Mostrar insignia de prioridad en tarjetas de tareas",
"description": "Como usuario, quiero ver la prioridad de la tarea de un vistazo.",
"acceptanceCriteria": [
"La insignia muestra P1/P2/P3/P4 con colores",
"La insignia es visible sin pasar el ratón",
"pnpm typecheck pasa",
"pnpm lint pasa",
"Verificar en el navegador usando el skill dev-browser"
],
"priority": 2,
"passes": false,
"notes": "",
"dependsOn": ["US-001"]
},
{
"id": "US-003",
"title": "Añadir menú desplegable de filtro por prioridad",
"description": "Como usuario, quiero filtrar tareas por prioridad.",
"acceptanceCriteria": [
"Menú desplegable de filtro: Todas, P1, P2, P3, P4",
"El filtro persiste en la URL",
"pnpm typecheck pasa",
"pnpm lint pasa",
"Verificar en el navegador usando el skill dev-browser"
],
"priority": 3,
"passes": false,
"notes": "",
"dependsOn": ["US-002"]
}
]
}
Ejecutar con ralph-tui
Después de crear prd.json:
ralph-tui run --prd ./tasks/prd.json
Ralph-tui:
- Cargará las historias desde prd.json
- Seleccionará la historia de mayor prioridad con
passes: falsey sin dependencias bloqueantes - Generará un prompt con los detalles de la historia + criterios de aceptación
- Ejecutará el agente para implementar la historia
- Marcará
passes: trueal completarse - Repetirá hasta que todas las historias pasen
Lista de Verificación Antes de Guardar
- Puertas de Calidad extraídas del PRD (o preguntado al usuario si faltan)
- Cada historia se puede completar en una iteración
- Historias ordenadas por dependencia (esquema → backend → UI)
-
dependsOnconfigurado correctamente para cada historia - Puertas de calidad añadidas a los criterios de aceptación de cada historia
- Las historias de UI tienen verificación en navegador (si se especifica en Puertas de Calidad)
- Los criterios de aceptación son verificables (no vagos)
- No hay dependencias circulares