Skip to content

Using Runbooks

/rai-story-run, /rai-bugfix-run, and /rai-epic-run were removed in RaiSE 3.0. Prefer the MCP pipeline engine directly. This page remains as migration guidance and historical context.

Runbooks were skill chains that ran the full lifecycle automatically, pausing only at fixed Human-in-the-Loop (HITL) gates. They were the middle ground between manual skills and the current MCP pipeline engine.

Legacy Runbooks

Runbook Skill Phases HITL Gates When to use
Story /rai-story-run 6 2 (design, implementation) Features, enhancements
Bugfix /rai-bugfix-run 7 historically; current pipeline has 10 3 historically; current pipeline has review gates Tracked bugs
Epic /rai-epic-run 6 2 (design, plan) Multi-story initiatives

Replacing a Story Runbook

Start the story pipeline for RAISE-456

The current story pipeline:

  1. Starts the story (branch, scope commit)
  2. Designs the specification (gemba walk, lean gates)
  3. Pauses at GATE 1: Design Approval — you review the approach
  4. Plans atomic tasks with TDD
  5. Implements all tasks
  6. Pauses at GATE 2: Code Review — you verify the implementation
  7. Reviews and extracts learnings
  8. Closes the story (merge, cleanup)

What happens at a gate

── GATE 1: Design Approval ──

Story: RAISE-456 — Add webhook notifications

Approach: Event-driven via existing hook system.
Components: hooks/webhook.py (new), config schema (modify)
Lean check: KISS ✓, DRY ✓, YAGNI ✓

▸ Approve design? [y/edit/reject]
  • y — continue to next phase
  • edit — adjust the approach, then continue
  • reject — stop the runbook entirely

Phase detection (resume)

If your session is interrupted, ask Rai to resume the pipeline:

Resume the story pipeline for RAISE-456

The MCP pipeline engine restores persisted run state and resumes from the last completed phase.

Replacing a Bugfix Runbook

Start the bugfix pipeline for RAISE-789

The current bugfix pipeline has 10 phases:

Phase What Gate after?
Start Reproduce, create scope
Triage Classify (type, severity, origin) GATE 1: Scope
Analyse Root cause analysis GATE 2: Strategy
Plan Decompose fix into tasks
Architecture Review Proportionality and design review GATE 3: Architecture Review
Fix TDD implementation GATE 4: Verification
Quality Review Semantic bugs, regression risk, test quality GATE 5: Quality Review
Review Retrospective, patterns
PIR Optional post-incident review Optional
Close Push, MR, Jira transition

Gate 2 is the highest-value gate

After analysis, the runbook presents multiple fix approaches with trade-offs:

── GATE 2: Root Cause & Strategy ──

Root cause: Config reader ignores existing values on re-init
Method: Direct (Gemba)

Fix approaches:
  A: Preserve existing values as defaults — 10 lines, minimal risk
  B: Deep-merge strategy — cleaner, but complex nested model handling
  C: Separate first-init vs re-init paths — most explicit, more code

Recommended: A

▸ Which approach? [a/b/c/adjust/reject]

This gate prevents over-engineering — always bias toward the simplest fix.

Running an Epic Runbook

/rai-epic-run RAISE-1000

The legacy epic runbook orchestrated the full epic lifecycle:

  1. Start — initialize directory, scope, backlog entry
  2. Design — architecture, stories, dependencies
  3. Pauses at GATE 1: Design — you review scope and stories
  4. Plan — sequence stories, milestones
  5. Pauses at GATE 2: Plan — you review the plan
  6. Story iteration — execute each story
  7. Docs — architecture documentation
  8. Close — retrospective, merge

MCP Tools in Legacy Runbooks

Runbooks used MCP tools for structured operations:

  • raise_graph_query — load patterns and context at each phase
  • raise_backlog_transition — track progress in Jira
  • raise_pattern_add — persist learnings during review
  • raise_gate_check — run quality gates (tests, types, lint)

Current RaiSE 3.x pipelines require the rai-workspace MCP server; the removed runbooks are not a fallback path.

When to Graduate from Manual Skills

Historically, runbooks were appropriate when:

  • You've completed 5-10 stories using individual skills
  • You understand what each phase produces and why
  • You trust the AI's design and implementation output
  • You wanted to move faster without skipping rigor

You're not ready if:

  • You're new to the codebase
  • The work is high-risk or novel
  • You need to deeply understand each step (learning mode)

For those cases in RaiSE 3.x, stay at Level 1 (individual skills).

When to Graduate to Pipelines

In RaiSE 3.x, use pipelines for:

  • Standardizing your team's workflow in YAML
  • Persisting state across sessions
  • Customizing phases per project
  • Tuning delegation levels for different story types

See Autonomy Levels for the full progression model.