Saltar a contenido

Usando Runbooks

/rai-story-run, /rai-bugfix-run y /rai-epic-run están deprecados. Prefiere usar el pipeline engine directamente. Esta página queda como guía de migración y contexto histórico.

Los runbooks son cadenas de skills que ejecutan el ciclo de vida completo automáticamente, pausando solo en gates HITL (Human-in-the-Loop) fijos. Son el punto medio: velocidad de automatización con la seguridad del juicio humano en decisiones críticas.

Runbooks Disponibles

Runbook Skill Fases Gates HITL Cuándo usar
Story /rai-story-run 6 2 (diseño, implementación) Features, mejoras
Bugfix /rai-bugfix-run 7 3 (scope, análisis, fix) Bugs rastreados
Epic /rai-epic-run 6 2 (diseño, plan) Iniciativas multi-story

Ejecutar un Runbook de Story

/rai-story-run RAISE-456

El runbook:

  1. Inicia la story (branch, scope commit)
  2. Diseña la especificación (gemba walk, gates lean)
  3. Pausa en GATE 1: Aprobación de Diseño — revisas el enfoque
  4. Planifica tareas atómicas con TDD
  5. Implementa todas las tareas
  6. Pausa en GATE 2: Revisión de Código — verificas la implementación
  7. Revisa y extrae aprendizajes
  8. Cierra la story (merge, limpieza)

Qué pasa en un gate

── GATE 1: Aprobación de Diseño ──

Story: RAISE-456 — Agregar notificaciones webhook

Enfoque: Event-driven via sistema de hooks existente.
Componentes: hooks/webhook.py (nuevo), schema config (modificar)
Check lean: KISS ✓, DRY ✓, YAGNI ✓

▸ ¿Aprobar diseño? [y/edit/reject]
  • y — continuar a la siguiente fase
  • edit — ajustar el enfoque, luego continuar
  • reject — detener el runbook

Detección de fase (resume)

Si tu sesión se interrumpe, invoca el runbook de nuevo:

/rai-story-run RAISE-456

Revisa los artefactos en orden inverso y reanuda desde la última fase completada. No se pierde trabajo.

Ejecutar un Runbook de Bugfix

/rai-bugfix-run RAISE-789

El runbook de bugfix tiene 7 fases y 3 gates:

Fase Qué ¿Gate después?
Start Reproducir, crear scope
Triage Clasificar (tipo, severidad, origen) GATE 1: Scope
Analyse Análisis de causa raíz GATE 2: Estrategia
Plan Descomponer fix en tareas
Fix Implementación TDD GATE 3: Verificación
Review Retrospectiva, patrones
Close Push, MR, transición Jira

Gate 2 es el gate de mayor valor

Después del análisis, el runbook presenta múltiples enfoques de fix con trade-offs:

── GATE 2: Causa Raíz y Estrategia ──

Causa raíz: El lector de config ignora valores existentes en re-init
Método: Directo (Gemba)

Enfoques de fix:
  A: Preservar valores existentes como defaults — 10 líneas, riesgo mínimo
  B: Estrategia deep-merge — más limpio, pero manejo complejo de modelos
  C: Separar rutas first-init vs re-init — más explícito, más código

Recomendado: A

▸ ¿Qué enfoque? [a/b/c/adjust/reject]

Este gate previene la sobre-ingeniería — siempre sesga hacia el fix más simple.

Ejecutar un Runbook de Epic

/rai-epic-run RAISE-1000

Orquesta el ciclo completo del epic:

  1. Start — inicializar directorio, scope, entrada en backlog
  2. Design — arquitectura, stories, dependencias
  3. Pausa en GATE 1: Diseño — revisas scope y stories
  4. Plan — secuenciar stories, milestones
  5. Pausa en GATE 2: Plan — revisas el plan
  6. Story iteration — ejecutar cada story (usando runbooks de story)
  7. Docs — documentación de arquitectura
  8. Close — retrospectiva, merge

MCP Tools en Runbooks

Los runbooks usan MCP tools para operaciones estructuradas:

  • raise_graph_query — cargar patrones y contexto en cada fase
  • raise_backlog_transition — rastrear progreso en Jira
  • raise_pattern_add — persistir aprendizajes durante review
  • raise_gate_check — ejecutar quality gates (tests, types, lint)

Si los MCP tools no están disponibles, los runbooks caen a comandos CLI automáticamente.

Cuándo Graduarte de Skills Manuales

Estás listo para runbooks cuando:

  • Has completado 5-10 stories usando skills individuales
  • Entiendes qué produce cada fase y por qué
  • Confías en el output de diseño e implementación del AI
  • Quieres ir más rápido sin sacrificar rigor

No estás listo si:

  • Eres nuevo en el codebase
  • El trabajo es de alto riesgo o novel
  • Necesitas entender cada paso a profundidad (modo aprendizaje)

Para esos casos, quédate en Nivel 1 (skills individuales).

Cuándo Graduarte a Pipelines

Después de completar un epic con runbooks, considera pipelines para:

  • Estandarizar el flujo de tu equipo en YAML
  • Persistir estado entre sesiones
  • Personalizar fases por proyecto
  • Ajustar niveles de delegación por tipo de story

Ver Niveles de Autonomía para el modelo completo de progresión.