Ralph TUI - Crear Beads
Convierte PRDs en beads (epic + tareas hijas) para la ejecución autónoma de ralph-tui.
Nota: Este skill está incluido con el plugin de tracker Beads de ralph-tui. Los futuros plugins de tracker (Linear, GitHub Issues, etc.) incluirán sus propios skills de creación de tareas.
El Trabajo
Toma un PRD (archivo markdown o texto) y crea beads en .beads/beads.jsonl:
- Extraer Puertas de Calidad de la sección "Quality Gates" del PRD
- Crear un bead epic para la funcionalidad
- Crear beads hijo para cada historia de usuario (con las puertas de calidad añadidas)
- Configurar dependencias entre beads (esquema → backend → UI)
- Salida lista para
ralph-tui run --tracker beads
Paso 1: Extraer Puertas de Calidad
Busca la sección "Quality Gates" en el PRD:
## Quality Gates
Estos comandos deben pasar para cada historia de usuario:
- `pnpm typecheck` - Verificación de tipos
- `pnpm lint` - Linting
Para historias de UI, incluye también:
- Verificar en el navegador usando el skill dev-browser
Extrae:
- Puertas universales: Comandos que aplican a TODAS las historias (ej.
pnpm typecheck) - Puertas de UI: Comandos que aplican solo a historias de UI (ej. verificación en navegador)
Si no existe la sección "Quality Gates": Pregunta al usuario qué comandos deberían pasar, o usa un valor predeterminado sensato como npm run typecheck.
Formato de Salida
Los beads usan el comando bd create con sintaxis HEREDOC para manejar de forma segura caracteres especiales:
# Crear epic (enlazar al PRD fuente)
bd create --type=epic \
--title="[Nombre de la funcionalidad]" \
--description="$(cat <<'EOF'
[Descripción de la funcionalidad del PRD]
EOF
)" \
--external-ref="prd:./tasks/feature-name-prd.md"
# Crear bead hijo (con puertas de calidad en los criterios de aceptación)
bd create \
--parent=EPIC_ID \
--title="[Título de la historia]" \
--description="$(cat <<'EOF'
[Descripción de la historia con criterios de aceptación INCLUYENDO puertas de calidad]
EOF
)" \
--priority=[1-4]
CRÍTICO: Usa siempre
<<'EOF'(con comillas simples) para el delimitador HEREDOC. Esto evita que el shell interprete backticks,$variablesy()en las descripciones.
Tamaño de la Historia: La Regla #1
Cada historia debe ser completable en UNA iteración de ralph-tui (~una ventana de contexto del agente).
ralph-tui crea una instancia nueva del agente 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:
- Agregar una columna de base de datos + migración
- Agregar un componente UI a una página existente
- Actualizar una server action con nueva lógica
- Agregar un menú desplegable de filtro a una lista
Demasiado grandes (dividir estas):
- "Construir todo el dashboard" → Dividir en: esquema, consultas, componentes UI, filtros
- "Agregar 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.
Orden de las Historias: Dependencias Primero
Las historias se ejecutan en orden de dependencia. Las historias anteriores no deben depender de las posteriores.
Orden correcto:
- Cambios de esquema/base de datos (migraciones)
- Server actions / lógica de backend
- Componentes UI que usan el backend
- Vistas de dashboard/resumen que agregan datos
Orden incorrecto:
- ❌ Componente UI (depende de un esquema que aún no existe)
- ❌ Cambio de esquema
Dependencias con bd dep add
Usa el comando bd dep add para especificar qué beads deben completarse primero:
# Crear primero los beads
bd create --parent=epic-123 --title="US-001: Agregar esquema" ...
bd create --parent=epic-123 --title="US-002: Crear API" ...
bd create --parent=epic-123 --title="US-003: Construir UI" ...
# Luego agregar dependencias (la tarea depende del bloqueador)
bd dep add ralph-tui-002 ralph-tui-001 # US-002 depende de US-001
bd dep add ralph-tui-003 ralph-tui-002 # US-003 depende de US-002
Sintaxis: bd dep add <tarea> <depende-de> — la tarea depende de (está bloqueada por) depende-de.
ralph-tui hará lo siguiente:
- Mostrará los beads bloqueados como "bloqueados" hasta que las dependencias se completen
- Nunca seleccionará un bead para ejecución mientras sus dependencias estén abiertas
- Incluirá el contexto de dependencia en el prompt al trabajar en un bead
Orden de dependencia correcto:
- Cambios de esquema/base de datos (sin dependencias)
- Lógica de backend (depende del esquema)
- Componentes UI (dependen del backend)
- Integración/pulido (depende de UI)
Criterios de Aceptación: Puertas de Calidad + Específicos de la Historia
La descripción de cada bead debe incluir criterios de aceptación con:
- Criterios específicos de la historia del PRD (lo que logra esta historia)
- Puertas de calidad de la sección "Quality Gates" del PRD (añadidas al final)
Bueno criterios (verificables):
- "Agregar columna
investorTypea la tabla investor con valor predeterminado 'cold'" - "El menú desplegable de filtro tiene opciones: Todas, Cold, Friend"
- "Al hacer clic en el toggle se 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 → un bead
- Primera historia: Sin dependencias (crea la base)
- Historias siguientes: Dependen de sus predecesoras (UI depende del backend, etc.)
- Prioridad: Basada en el orden de dependencia, luego en el orden del documento (0=crítico, 2=medio, 4=backlog)
- Todas las historias:
status: "open" - 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)
División de PRDs Grandes
Si un PRD tiene funcionalidades grandes, divídelas:
Original:
"Agregar seguimiento de contactos de amigos con mensajería diferente"
Dividido en:
- US-001: Agregar campo investorType a la base de datos
- US-002: Agregar toggle de tipo a la lista de inversionistas en UI
- US-003: Crear lógica de progresión de fase específica para amigos
- US-004: Crear plantillas de mensajes para amigos
- US-005: Implementar generación de tareas para amigos
- US-006: Agregar filtro por tipo
- US-007: Actualizar formulario de nuevo inversionista
- US-008: Actualizar conteos del dashboard
Cada uno es un cambio enfocado que se puede completar y verificar de forma independiente.
Ejemplo
PRD de entrada:
# PRD: Seguimiento de Amigos
Agregar la capacidad de marcar inversionistas como "amigos" para contacto cálido.
## Quality Gates
Estos comandos deben pasar para cada historia de usuario:
- `pnpm typecheck` - Verificación de tipos
- `pnpm lint` - Linting
Para historias de UI, incluye también:
- Verificar en el navegador usando el skill dev-browser
## Historias de Usuario
### US-001: Agregar campo investorType a la tabla investor
**Descripción:** Como desarrollador, necesito categorizar inversionistas como 'cold' o 'friend'.
**Criterios de Aceptación:**
- [ ] Agregar columna investorType: 'cold' | 'friend' (predeterminado 'cold')
- [ ] Generar y ejecutar migración exitosamente
### US-002: Agregar toggle de tipo a las filas de la lista de inversionistas
**Descripción:** Como Ryan, quiero cambiar el tipo de inversionista directamente desde la lista.
**Criterios de Aceptación:**
- [ ] Cada fila tiene un toggle Cold | Friend
- [ ] Al cambiar, se muestra un diálogo de confirmación
- [ ] Al confirmar: actualiza el tipo en la base de datos
### US-003: Filtrar inversionistas por tipo
**Descripción:** Como Ryan, quiero filtrar la lista para ver solo amigos o cold.
**Criterios de Aceptación:**
- [ ] Menú desplegable de filtro: Todas | Cold | Friend
- [ ] El filtro persiste en los parámetros de URL
Beads de salida:
# Crear epic (enlazar al PRD fuente)
bd create --type=epic \
--title="Seguimiento de Amigos" \
--description="$(cat <<'EOF'
Contacto cálido para obtener retroalimentación de presentaciones
EOF
)" \
--external-ref="prd:./tasks/friends-outreach-prd.md"
# US-001: Sin deps (primero - crea el esquema)
bd create --parent=ralph-tui-abc \
--title="US-001: Agregar campo investorType a la tabla investor" \
--description="$(cat <<'EOF'
Como desarrollador, necesito categorizar inversionistas como 'cold' o 'friend'.
## Criterios de Aceptación
- [ ] Agregar columna investorType: 'cold' | 'friend' (predeterminado 'cold')
- [ ] Generar y ejecutar migración exitosamente
- [ ] pnpm typecheck pasa
- [ ] pnpm lint pasa
EOF
)" \
--priority=1
# US-002: Historia de UI (también obtiene verificación en navegador)
bd create --parent=ralph-tui-abc \
--title="US-002: Agregar toggle de tipo a las filas de la lista de inversionistas" \
--description="$(cat <<'EOF'
Como Ryan, quiero cambiar el tipo de inversionista directamente desde la lista.
## Criterios de Aceptación
- [ ] Cada fila tiene un toggle Cold | Friend
- [ ] Al cambiar, se muestra un diálogo de confirmación
- [ ] Al confirmar: actualiza el tipo en la base de datos
- [ ] pnpm typecheck pasa
- [ ] pnpm lint pasa
- [ ] Verificar en el navegador usando el skill dev-browser
EOF
)" \
--priority=2
# Agregar dependencia: US-002 depende de US-001
bd dep add ralph-tui-002 ralph-tui-001
# US-003: Historia de UI
bd create --parent=ralph-tui-abc \
--title="US-003: Filtrar inversionistas por tipo" \
--description="$(cat <<'EOF'
Como Ryan, quiero filtrar la lista para ver solo amigos o cold.
## Criterios de Aceptación
- [ ] Menú desplegable de filtro: Todas | Cold | Friend
- [ ] El filtro persiste en los parámetros de URL
- [ ] pnpm typecheck pasa
- [ ] pnpm lint pasa
- [ ] Verificar en el navegador usando el skill dev-browser
EOF
)" \
--priority=3
# Agregar dependencia: US-003 depende de US-002
bd dep add ralph-tui-003 ralph-tui-002
Ubicación de Salida
Los beads se escriben en: .beads/beads.jsonl
Después de la creación, ejecuta ralph-tui:
# Trabajar en un epic específico
ralph-tui run --tracker beads --epic ralph-tui-abc
# O dejar que seleccione la mejor tarea automáticamente
ralph-tui run --tracker beads
ralph-tui hará lo siguiente:
- Trabajará en los beads dentro del epic especificado (o seleccionará la mejor tarea disponible)
- Cerrará cada bead cuando esté completo
- Cerrará el epic cuando todos los hijos estén terminados
- Mostrará
<promise>COMPLETE</promise>cuando el epic esté completo
Lista de Verificación Antes de Crear Beads
- Extraídas las Puertas de Calidad del PRD (o preguntado al usuario si faltan)
- Cada historia es completable en una iteración (suficientemente pequeña)
- Las historias están ordenadas por dependencia (esquema → backend → UI)
- Las puertas de calidad se han añadido a los criterios de aceptación de cada bead
- Las historias de UI tienen verificación en navegador (si está especificado en las Puertas de Calidad)
- Los criterios de aceptación son verificables (no vagos)
- Ninguna historia depende de una historia posterior (solo de anteriores)
- Se han agregado dependencias con
bd dep adddespués de crear los beads