Skip to main content
Tutorial

Reflex repair playbooks in YAML — structure and examples

The Reflex Team9 min12 May 2026

Playbooks are how you tell Reflex what is allowed when a signal matches. YAML keeps them reviewable in Git and readable in incident postmortems.

Note: Exact schema keys evolve by version — treat this article as a mental model, not a normative spec. The in-app playbook editor and catalogue export are the source of truth for your build.

Top-level ideas

A playbook generally declares:

  • Identity — stable id, human title, description for operators.
  • Match — which signals or metric windows trigger consideration (service names, log patterns, thresholds).
  • Risk tier — LOW / MEDIUM / HIGH gating which environments may auto-run.
  • Actions — ordered steps the agent may execute (service reload, cache clear, disk cleanup patterns, etc.).
  • Guards — preconditions that must be true before each step (paths exist, disk still above X, pool not already reloading).

Example (illustrative, shortened)

id: php_fpm_graceful_reload_v1
title: Graceful PHP-FPM pool reload
risk: medium
match:
  service: php-fpm
  signals:
    - type: fpm_listen_queue_sustained
      threshold_seconds: 45
actions:
  - type: systemd_reload
    unit: php8.3-fpm
guards:
  - type: max_executions_per_hour
    value: 3

The real catalogue ships richer metadata — cooldowns, rollback hints, dry-run behaviour, and links to documentation.

Dry-run first

Most teams start with dry-run or confirm-only for anything that touches production traffic paths. Reflex records what would have happened — invaluable for tuning thresholds before you trust automation.

Review workflow

Treat playbooks like application code: PR review, staging validation, staged rollout. Reflex honours team boundaries — unauthorised edits should never appear from the guest internet (see product security docs for your edition).

Learn more