Using Runbooks

/rai-story-run, /rai-bugfix-run, and /rai-epic-run are deprecated. Prefer the pipeline engine directly. This page remains as migration guidance and historical context.

Runbooks are skill chains that run the full lifecycle automatically, pausing only at fixed Human-in-the-Loop (HITL) gates. They're the middle ground: you get the speed of automation with the safety of human judgment at critical decisions.

Available Runbooks

Runbook	Skill	Phases	HITL Gates	When to use
Story	/rai-story-run	6	2 (design, implementation)	Features, enhancements
Bugfix	/rai-bugfix-run	7	3 (scope, analysis, fix)	Tracked bugs
Epic	/rai-epic-run	6	2 (design, plan)	Multi-story initiatives

Running a Story Runbook

/rai-story-run RAISE-456

The runbook:

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, invoke the runbook again:

/rai-story-run RAISE-456

It checks artifacts in reverse order and resumes from the last completed phase. No work is lost.

Running a Bugfix Runbook

/rai-bugfix-run RAISE-789

The bugfix runbook has 7 phases and 3 gates:

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
Fix	TDD implementation	GATE 3: Verification
Review	Retrospective, patterns
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 epic runbook orchestrates 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 (using story runbooks)
7. Docs — architecture documentation
8. Close — retrospective, merge

MCP Tools in Runbooks

Runbooks use 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)

If MCP tools aren't available, runbooks fall back to CLI commands automatically. Nothing breaks.

When to Graduate from Manual Skills

You're ready for runbooks 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 want 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, stay at Level 1 (individual skills) — there's no shame in manual control.

When to Graduate to Pipelines

After completing an epic with runbooks, consider 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.