SLO & Error Budget Document — SLI targets and burn-rate

The slo-error-budget-document skill produces a rigorous SLO document that turns “the service should be reliable” into a specific, measurable, and enforceable contract. Every other reliability artifact in the engineering-docs suite — the runbook, the deployment plan, the postmortem — references an SLA/SLO without defining one; this skill is where that number comes from, how it is justified, and what happens when it is breached. An SLO without an error budget policy is just a wish: this skill applies Google SRE Workbook principles to give it teeth.

Type: Workflow · Estimated time: 2–4 hours · Standards: Google SRE Workbook — multi-window multi-burn-rate alerting · Output file: .engineering-docs/19-slo-error-budget.md · Conditional skill — include once real users depend on the service’s uptime and especially before committing to an external SLA with customers or partners.

Best for

Pre-launch reliability targets

Defining reliability targets for a new or existing service before launch, before “the service seems fine” becomes the only metric.

External SLA with margin

Formalizing a customer-facing SLA backed by an internal SLO with a deliberate buffer to absorb missed internal targets.

Velocity vs. reliability conflicts

Resolving recurring debates between shipping velocity and reliability work with data instead of opinion — the error budget is the arbiter.

Alert threshold source of truth

Setting the exact alerting thresholds that a runbook’s alert-response procedures are triggered by.

What it produces

The generated SLO document covers the full lifecycle from measurement to policy enforcement:

Section	Purpose
Overview & Critical User Journeys	Maps SLIs back to real user actions — not infrastructure metrics
SLIs with Implementation Queries	Exact Prometheus/Datadog queries that implement each indicator
SLOs	Numeric targets per SLI with measurement windows and evidence-based rationale
Error Budget Calculation	Budget in concrete terms (e.g., “43 minutes of full downtime-equivalent per 30 days”)
Multi-Window Burn-Rate Alerts	Three alert tiers: fast burn (page now), moderate burn (page soon), slow burn (ticket)
Error Budget Policy	Pre-agreed policy at four budget levels — from “ship normally” to “feature freeze”
Error Budget Dashboard	Panel-by-panel dashboard design that answers “how much budget remains?” in 5 seconds
Alerting Rule Implementation	Deployable Prometheus YAML rules and Datadog monitor configuration
SLO Breach Response Procedure	Different procedures for internal SLO breach vs. external SLA breach
External SLA & Buffer Sizing	Explicit gap between internal SLO and external SLA, sized by incident frequency and MTTR
Dependency-Aware SLOs	Composite SLO calculated from dependency chain; shared-fate risks documented
Review & Re-Baselining	Quarterly review structure with agenda, attendees, and decision authority

How to invoke it

Pass the service or API name as the argument. Providing historical uptime data, any existing external SLA, and your monitoring stack gives the agent everything it needs to set justified targets rather than round numbers.

claude "Define SLOs for our checkout API. We currently have no formal target — customers complain when checkout is slow but we've never quantified it. We use Prometheus/Grafana for metrics. We are not yet contractually bound to any external SLA."

gemini "Define SLOs for our checkout API. We currently have no formal target — customers complain when checkout is slow but we've never quantified it. We use Prometheus/Grafana for metrics. We are not yet contractually bound to any external SLA."

npx engineering-docs slo-error-budget-document "checkout API"

Example scenarios

Pre-SLA checkout API

Define SLOs for our checkout API before we commit to an uptime SLA with customersProduces SLI definitions for availability, latency, and payment durability with Prometheus queries, 99.9% SLO targets justified by baseline data, and a burn-rate alert set ready to deploy.

Error budget policy for feature freeze decisions

Set up error budget policy for the checkout service so we stop debating whether to freeze feature work after each blipProduces a pre-agreed four-level policy (healthy → low → exhausted) signed off by both engineering and the product stakeholder — so the decision is made once calmly, not every time an incident fires.

Webhook delivery pipeline

Write the SLI/SLO document for our webhook delivery pipeline and the burn-rate alerts that should page on-callCovers delivery success rate and end-to-end latency SLIs with a 99.5% delivery SLO, error budget of ~216 minutes per 30 days, and a full multi-window alert set with Prometheus rules.

Key concepts

SLI, SLO, SLA — not the same thing

Term	What it is	Example
SLI	A direct measurement of user-facing behavior	Proportion of checkout requests completing successfully
SLO	The internal target for an SLI over a time window	99.9% of checkout requests succeed, rolling 30 days
SLA	An external, often contractual, promise — looser than the SLO	99.5% monthly, with service credits for breach

Never set the SLA equal to the SLO. The gap is the buffer that lets you miss the internal target occasionally without breaching a customer contract and triggering financial penalties.

Why not 100%

100% reliability eliminates the error budget entirely — every deploy, migration, or experiment becomes a potential SLO breach. The error budget (1 − SLO) is the amount of unreliability the business has explicitly decided is an acceptable cost of moving fast. The SLO document makes that trade-off deliberate and visible.

Multi-window, multi-burn-rate alerting

A single “error rate > X%” alert either fires too late for fast, severe burns or too often for slow, minor ones. The skill implements the Google SRE Workbook three-tier model:

Alert tier	Burn rate	Long window	Short window	Budget consumed	Action
Fast burn	14.4×	1 hour	5 min	2% of monthly budget in 1 hr	Page immediately — critical
Moderate burn	6×	6 hours	30 min	5% in 6 hours	Page on-call — urgent
Slow burn	1×	3 days	6 hours	10% in 3 days	File ticket — investigate this week

Error budget policy

The policy is only useful if it is agreed upon before the budget is exhausted — not argued about mid-incident:

Budget remaining	Policy
> 50%	Ship normally
20–50%	Increase deploy review rigor; avoid risky changes without extra sign-off
< 20%	Feature work slows; reliability fixes get priority
0%	Feature freeze until budget recovers, or explicit leadership sign-off to continue at accepted risk

SLI implementation details

An SLI definition is incomplete without an exact monitoring query. The document includes ready-to-deploy Prometheus and Datadog implementations for each SLI, plus explicit documentation of any measurement gap (e.g., “measured at the load balancer — a database-side failure that does not produce a 5xx at the LB is not captured”).

Dependency-aware SLOs

Services do not operate in isolation. The document models the dependency chain and calculates the composite SLO ceiling. If a service depends on a database with a 99.95% SLO and an external API with a 99.5% SLO (without graceful degradation), the composite SLO ceiling is 99.5% — regardless of how well the service itself performs.

Interview process

The agent conducts a brief structured interview before drafting, loading prior .engineering-docs/ files first to avoid re-asking known facts:

Context loading

Reads existing documents (business-plan, technical-specification, system-architecture) to extract known uptime expectations, monitoring stack, and tech stack.

Reliability baseline (≤ 2–3 questions)

Asks what historical performance has looked like, if known — even rough estimates like “we’ve had two outages in the last quarter” inform target-setting.

External commitments

Checks whether an external SLA has already been promised to customers or partners, and what it says — this anchors the internal SLO target and the buffer calculation.

SLI selection

Chooses 2–4 SLIs per critical user journey — typically availability, latency, and correctness/durability — rejecting infrastructure metrics that do not reflect user experience.

SLO target setting

Sets the numeric target per SLI, justified by baseline data and business cost of missing it — not round numbers chosen for aesthetics.

Error budget and alerts

Calculates the error budget and defines the three-tier burn-rate alert thresholds with deployable monitoring rules.

Policy and review cadence

Defines the four-level error budget policy and the quarterly SLO review structure, with approval from both engineering and the business stakeholder who owns the roadmap.

Output structure

The generated .engineering-docs/19-slo-error-budget.md mirrors the full template:

19-slo-error-budget.md (structure)

# SLO & Error Budget Document

## 1. Overview
  ### 1.1 Purpose
  ### 1.2 Critical User Journeys
## 2. Service Level Indicators (SLIs)
  ### 2.1 SLI Implementation (Monitoring Queries)
      — Prometheus PromQL + Datadog metric per SLI
      — Implementation gaps documented
## 3. Service Level Objectives (SLOs)
      — Target, measurement window, evidence-based rationale
## 4. Error Budget
  ### 4.1 Budget Calculation
  ### 4.2 Multi-Window, Multi-Burn-Rate Alerts
## 5. Error Budget Policy
  ### 5.1 Error Budget Dashboard
  ### 5.2 Alerting Rule Implementation
      — Prometheus YAML rules (deployable)
      — Datadog monitor configuration
## 6. SLO Breach Response Procedure
  ### 6.1 Internal SLO Breach
  ### 6.2 External SLA Breach
## 7. External SLA (if applicable)
  ### 7.1 SLA Buffer Sizing
## 8. Dependency-Aware SLOs
  ### 8.1 Service Dependency Map
  ### 8.2 Dependency SLO Requirements & Composite Calculation
## 9. Review and Re-Baselining

Handoff

Reads from

1-business-plan.md — business cost of downtime, user expectations
5-technical-specification.md — performance and reliability requirements
7-system-architecture.md — components, dependencies, monitoring stack

Feeds into

17-technical-runbook.md — alert thresholds and response procedures
16-deployment-plan.md — deployment risk tolerance based on error budget
18-disaster-recovery.md — RTO/RPO targets derived from SLOs
Incident postmortems — severity classification and SLA impact measurement

Quality gate

Before marking the document final, verify every item in this checklist:

Common mistake: Setting the SLO at 100% or equal to the external SLA. 100% eliminates error budget entirely; SLA = SLO means any internal miss becomes a contractual breach. Both are addressed by the skill — but flag them explicitly if seen in a prior document.

Discovery & Planning

Specification & Architecture

Design & API

Quality & Delivery

Operations

SLO & Error Budget Document — SLI targets and burn-rate

Best for

Pre-launch reliability targets

External SLA with margin

Velocity vs. reliability conflicts

Alert threshold source of truth

What it produces

How to invoke it

Example scenarios

Key concepts

SLI, SLO, SLA — not the same thing

Why not 100%

Multi-window, multi-burn-rate alerting

Error budget policy

SLI implementation details

Dependency-aware SLOs

Interview process

Output structure

Handoff

Reads from

Feeds into

Quality gate

​Best for

Pre-launch reliability targets

External SLA with margin

Velocity vs. reliability conflicts

Alert threshold source of truth

​What it produces

​How to invoke it

​Example scenarios

​Key concepts

​SLI, SLO, SLA — not the same thing

​Why not 100%

​Multi-window, multi-burn-rate alerting

​Error budget policy

​SLI implementation details

​Dependency-aware SLOs

​Interview process

​Output structure

​Handoff

Reads from

Feeds into

​Quality gate

Best for

What it produces

How to invoke it

Example scenarios

Key concepts

SLI, SLO, SLA — not the same thing

Why not 100%

Multi-window, multi-burn-rate alerting

Error budget policy

SLI implementation details

Dependency-aware SLOs

Interview process

Output structure

Handoff

Quality gate