@diottodev/runic 1.0.0 → 1.1.0

package/engineering/skills/slo-architect/SKILL.md

@@ -0,0 +1,234 @@
+---
+name: slo-architect
+description: Use when defining, reviewing, or operating SLOs/SLIs/error budgets. Triggers on "define an SLO", "what should our SLO be", "error budget", "burn rate", "SLI", "service level objective", "Google SRE workbook", "multi-window burn-rate alert", or any reliability-target question. Ships SLO designer, error-budget calculator with multi-window burn-rate thresholds, and SLO reviewer that catches the common bugs (target too aggressive, window too short, conflicting SLOs, no SLI definition). 4 references on SLO principles + SLI design + error budget math + composition with feature-flags-architect/chaos-engineering/kubernetes-operator. NOT a generic observability skill — specifically the SLO discipline.
+context: fork
+version: 2.9.0
+author: claude-code-skills
+license: MIT
+tags: [slo, sli, sla, error-budget, burn-rate, sre, reliability, google-sre-workbook, observability]
+compatible_tools: [claude-code, codex-cli, cursor, antigravity, opencode, gemini-cli]
+---
+
+# SLO Architect
+
+Define SLOs that mean something. Most "SLOs" in the wild are arbitrary numbers no one believes — 99.9% on every endpoint, no SLI definition, no error budget, no policy for what happens when budget burns. This skill enforces the discipline from Google's SRE Workbook: pick the right SLI, set a target users actually care about, calculate the error budget, wire multi-window burn-rate alerts, and have a written policy for when budget runs out.
+
+## When to use
+
+- Defining a new SLO for a service or feature
+- Reviewing existing SLOs for common bugs
+- Picking the right SLI (event-based vs time-window based vs request-based)
+- Computing error budgets and burn-rate alert thresholds
+- Tying SLOs to existing controls — feature flags abort, chaos blast radius, operator capability levels
+
+## When NOT to use
+
+- General observability strategy (metrics + logs + traces) → use `observability-designer`
+- Customer-facing SLAs with legal teeth → that's contract drafting, not engineering
+- Performance load testing (capacity, not reliability) → use `performance-profiler`
+- Active incident response → use `incident-response`
+
+## Core principle: an SLO is a promise about user experience
+
+```
+SLI  ⟶  measurable signal of user-perceived health (e.g., HTTP 2xx rate)
+SLO  ⟶  target for the SLI over a window (e.g., 99.9% over 30 days)
+SLA  ⟶  customer-facing commitment with consequences (separate concern)
+EB   ⟶  error budget: 100% − SLO target = how much "bad" you can spend
+BR   ⟶  burn rate: how fast you're consuming the error budget
+```
+
+The four cardinal mistakes:
+
+1. **Target too high** (99.99%+ on services that can't support it) — every minor blip violates SLO; alerts become noise.
+2. **Wrong SLI** (CPU usage as proxy for user experience) — system can be "green" while users suffer.
+3. **No error budget policy** — burning budget means nothing if there's no agreed action.
+4. **Single-window burn-rate alert** — either too noisy (page on a 5-min spike) or too slow (notice budget exhausted after the fact).
+
+The 3 tools below catch each of these.
+
+## Quick start
+
+```bash
+SKILL=engineering/slo-architect/skills/slo-architect
+
+# 1. Design an SLO
+python "$SKILL/scripts/slo_designer.py" \
+  --service checkout-svc \
+  --sli-type request-success-rate \
+  --target 99.9 \
+  --window-days 30
+
+# 2. Compute error budget + multi-window burn-rate alerts
+python "$SKILL/scripts/error_budget_calculator.py" \
+  --target 99.9 --window-days 30
+
+# 3. Review existing SLO definitions for common bugs
+python "$SKILL/scripts/slo_review.py" --slo-doc docs/slos/
+```
+
+## The 3 Python tools
+
+All stdlib-only.
+
+### `slo_designer.py`
+
+Generates a structured SLO definition with required fields. Refuses to render if any required field is missing (`exit 1`).
+
+```bash
+python scripts/slo_designer.py \
+  --service checkout-svc \
+  --sli-type request-success-rate \
+  --target 99.9 \
+  --window-days 30 \
+  --owner team-checkout
+```
+
+**SLI types supported:**
+- `request-success-rate` — `(total_requests - bad_requests) / total_requests`
+- `request-latency` — `count(requests < threshold) / total_requests`
+- `availability-time` — `(window - downtime) / window`
+- `data-freshness` — `count(data_age < threshold) / total_data_points`
+- `correctness` — `count(correct_outputs) / total_outputs`
+
+Output is markdown by default with all required fields filled or marked `<must define>`. JSON output (`--format json`) is consumed by `slo_review.py`.
+
+### `error_budget_calculator.py`
+
+Given target availability + window, computes:
+- Allowed downtime in the window
+- Multi-window burn-rate thresholds per Google SRE Workbook (Chapter 5):
+  - **Fast burn** — page if 2% of monthly budget consumed in 1 hour
+  - **Slow burn** — page if 10% consumed in 6 hours, ticket if 10% in 3 days
+- Recommended alerting rules (PromQL-shaped output)
+
+```bash
+python scripts/error_budget_calculator.py --target 99.9 --window-days 30
+python scripts/error_budget_calculator.py --target 99.95 --window-days 7 --format json
+```
+
+### `slo_review.py`
+
+Audits a directory of SLO definitions (markdown or JSON) for the common bugs.
+
+```bash
+python scripts/slo_review.py --slo-doc docs/slos/
+```
+
+**Checks:**
+- `target_too_high`: target ≥ 99.99% (sustainable only with massive engineering investment)
+- `target_too_low`: target ≤ 99.0% (probably wrong SLI; users will notice)
+- `window_too_short`: window < 7 days (statistical noise dominates)
+- `window_too_long`: window > 90 days (slow feedback)
+- `no_sli_definition`: SLI section missing or vague ("everything OK")
+- `no_error_budget_policy`: no documented action when budget burns
+- `cpu_as_sli`: CPU/memory used as user-experience proxy (wrong signal)
+
+## SLI selection cheatsheet
+
+| User experience | SLI type | What you measure |
+|---|---|---|
+| "Did the request succeed?" | request-success-rate | `2xx / total` |
+| "Was the response fast?" | request-latency | `count(p99 < threshold) / total` |
+| "Was the service up?" | availability-time | `(window - downtime) / window` |
+| "Is the data current?" | data-freshness | `count(data_age < threshold) / total` |
+| "Was the answer correct?" | correctness | `count(correct) / total` |
+
+See `references/sli_design.md` for examples and anti-patterns.
+
+## Error budget math (the basics)
+
+For 99.9% SLO over 30 days:
+- Allowed unavailability: `0.1% × 30 × 24 × 60 = 43.2 minutes`
+- 1-hour fast-burn threshold (2% of monthly budget burned): `2% × 43.2 / 60 ≈ 1.44 ratio multiplier`
+- 6-hour slow-burn threshold (10% in 6h): `10% × 43.2 / 360 ≈ 0.6 ratio multiplier`
+
+`error_budget_calculator.py` does this math for you and emits ready-to-paste alert rules.
+
+## Composition with the rest of the portfolio
+
+This skill explicitly composes with three others:
+
+| Skill | Composition |
+|---|---|
+| `feature-flags-architect` | Rollout abort criteria reference SLO burn-rate thresholds |
+| `chaos-engineering` | Blast-radius calculator already takes monthly error budget as input — define it here |
+| `kubernetes-operator` | Operator capability L4 (Deep Insights) requires SLOs + Prometheus rules |
+
+The `error_budget_calculator.py` output is in the same shape `chaos-engineering/scripts/blast_radius_calculator.py` expects on stdin.
+
+## Workflows
+
+### Workflow 1: Define a new SLO
+
+```
+1. Pick the user journey to protect (e.g., "checkout completion").
+2. Choose SLI type (request-success-rate, latency, availability, freshness, correctness).
+3. Define the SLI precisely: numerator/denominator with concrete labels.
+4. Pick a target by measuring 30 days of historical SLI value:
+     target = floor(p50 of last 30 days × 100) / 100
+   This avoids targets the system has never sustained.
+5. Pick a window (28 days = 4 calendar weeks, recommended).
+6. Run slo_designer.py to render the SLO definition.
+7. Run error_budget_calculator.py to get burn-rate alerts.
+8. Write the error budget policy (what happens when budget burns).
+9. Run slo_review.py — must pass before the SLO is "live".
+```
+
+### Workflow 2: Quarterly SLO review
+
+```
+1. For every active SLO, run slo_review.py — fix any FAIL findings.
+2. Look at last quarter's data:
+   - Was the SLO too easy (never burned budget)? Tighten target.
+   - Was it too hard (frequently burned)? Loosen target OR fix the system.
+   - Did burn-rate alerts fire usefully (not too noisy, not too late)? Adjust thresholds.
+3. Audit error budget policies — were they actually followed when budget burned?
+4. Commit revised SLOs; archive old versions with date stamps.
+```
+
+### Workflow 3: SLO-driven rollback
+
+```
+1. New deploy starts burning error budget faster than baseline.
+2. Burn-rate alert fires (from error_budget_calculator.py thresholds).
+3. Auto-rollback via feature flag (kill switch from feature-flags-architect).
+4. Postmortem feeds into next SLO revision.
+```
+
+## References
+
+- `references/slo_principles.md` — SLI vs SLO vs SLA, Google SRE Workbook canon
+- `references/sli_design.md` — picking the right SLI; 5 types with examples
+- `references/error_budget.md` — error budget math, burn-rate alerts, budget policy
+- `references/composition.md` — how SLOs feed feature flags, chaos, operators
+
+## Slash command
+
+`/slo-design` — interactive SLO design wizard that runs all 3 tools.
+
+## Asset templates
+
+- `assets/slo_template.yaml` — fillable SLO YAML
+- `assets/error_budget_policy.md` — fillable policy template
+
+## Anti-patterns
+
+- **99.99% on every endpoint** — copy-paste SLOs that nobody verified the system can sustain
+- **CPU usage as SLI** — system metrics aren't user experience
+- **Single-window burn-rate alert** — too noisy if 5-min, too slow if 30-day
+- **No error budget policy** — burning budget means nothing without an action
+- **SLOs without owners** — no one is responsible; they bit-rot
+- **SLOs reviewed once a year** — system characteristics change faster than that
+- **SLAs in the SLO doc** — different audience, different stakes; keep them separate
+- **SLO target = SLA target** — SLO must be tighter (you should beat your contract before customers notice)
+
+## Verifiable success
+
+A team using this skill should achieve:
+
+- 100% of SLOs pass `slo_review.py` with 0 FAIL findings
+- Every SLO has a documented owner, error budget, burn-rate alerts, and policy
+- Burn-rate alerts fire ≤2 times/month per SLO that's hit (signal, not noise)
+- Mean time to detect SLO violation: <30 min (multi-window burn-rate alerts working)
+- Quarterly SLO review happens every quarter (not annually)

package/engineering/skills/slo-architect/assets/error_budget_policy.md

@@ -0,0 +1,79 @@
+# Error budget policy — `<service-name>`
+
+This policy says what changes when error budget is burned. Without it, the SLO is theater.
+
+## Scope
+
+Applies to: `<list of SLO IDs covered by this policy>`
+Owner: `<team-name>`
+Review cadence: quarterly
+Last reviewed: `<YYYY-MM-DD>`
+
+## States and actions
+
+### State: HEALTHY (>50% budget remaining)
+
+- Normal operation
+- Ship features without extra friction
+- Run chaos experiments per the standard cadence
+- Roll out feature flags per standard plan
+
+### State: CAUTION (25-50% budget remaining)
+
+- Risky changes get extra review (architect or staff sign-off)
+- No new chaos experiments outside dedicated windows
+- Postpone non-essential migrations
+- Daily team check on budget direction
+
+### State: CRITICAL (<25% budget remaining)
+
+- **Deploy freeze** for the affected service: only SLO-improving fixes ship
+- All releases require **explicit owner sign-off**
+- **Chaos experiments paused**
+- **Feature flag rollouts paused** (existing flags continue at current percent)
+- Daily standup includes budget status
+
+### State: VIOLATED (budget exhausted, SLO target missed)
+
+- Same-day: stop the bleeding (rollback, kill switch, scale up)
+- Within 48 hours: blameless postmortem published
+- Within 14 days: at least one follow-up action shipped
+- Within 30 days: review whether SLO target/window are still right
+
+## Recovery
+
+After exiting VIOLATED, the service stays in CRITICAL until:
+- Burn rate is sustained at <1× over 7 consecutive days, AND
+- All postmortem follow-ups are shipped
+
+## Roles
+
+| Role | Responsibility |
+|---|---|
+| Service owner | Triggers state transitions; communicates to stakeholders |
+| On-call | Receives burn-rate alerts; initial triage |
+| Engineering manager | Approves deploys during CRITICAL/VIOLATED |
+| SRE | Reviews SLO target appropriateness quarterly |
+
+## Exceptions
+
+The deploy freeze can be lifted by:
+- Service owner + engineering manager joint approval
+- Reason documented (security fix, customer escalation, regulatory)
+- Logged for postmortem review
+
+## Reviewing this policy
+
+This policy is reviewed every quarter. Questions to ask:
+1. Did we follow the policy when budget burned?
+2. Are the thresholds (50% / 25%) right?
+3. Are the actions (freeze, sign-off) actually happening?
+4. Did the SLO target need to change?
+
+Answers feed into the next quarter's revision.
+
+## Composition references
+
+- `references/composition.md` — how this policy interacts with feature-flags-architect, chaos-engineering, kubernetes-operator
+- `references/error_budget.md` — the math behind the thresholds
+- `references/slo_principles.md` — Google SRE Workbook canon

package/engineering/skills/slo-architect/assets/slo_template.yaml

@@ -0,0 +1,63 @@
+# SLO definition — fill in <PLACEHOLDERS>
+# Pass this through slo_review.py before going live.
+---
+slo_id: slo-<service>-<sli_type>-<unix_ts>
+service: <service-name>                # e.g., checkout-svc
+owner: <team-or-handle@org>             # required; named individual or team
+created: <YYYY-MM-DD>
+review_cadence: quarterly               # quarterly | monthly | weekly
+
+# The user journey this SLO protects.
+# Be specific. NOT "API works" — instead "User completes checkout in <2s".
+user_journey: <describe the user journey>
+
+# The SLI: a measurable signal of user-perceived health.
+sli:
+  type: request-success-rate            # request-success-rate | request-latency
+                                        # | availability-time | data-freshness | correctness
+  numerator: count(http_requests_total{job="<service>", status_code=~"2..|3.."})
+  denominator: count(http_requests_total{job="<service>", source!="bot"})
+  labels:
+    - env=prod
+    - region=us-east-1
+
+# The target value the SLI must hit over the window.
+# Pick from data: floor(p50 of last 30d × 100) / 100.
+# Don't copy 99.9% blindly.
+target_percent: 99.9
+window_days: 28                         # 7 / 28 / 30 / 90 — default 28
+
+error_budget:
+  # Computed by error_budget_calculator.py — confirm the math.
+  minutes_per_window: <40.32 for 99.9% over 28 days>
+  # Path or URL to the error budget policy.
+  # The policy must answer: "When budget burns to 25% / 0%, what changes?"
+  policy_doc: <link required before SLO is live>
+
+# Burn-rate alert thresholds, computed by error_budget_calculator.py.
+# Multi-window per Google SRE Workbook Chapter 5.
+alerts:
+  fast_burn:
+    long_window: 1h
+    short_window: 5m
+    burn_rate_threshold: <from error_budget_calculator.py>
+    severity: page
+  slow_burn:
+    long_window: 6h
+    short_window: 30m
+    burn_rate_threshold: <from error_budget_calculator.py>
+    severity: page
+  ticket_burn:
+    long_window: 3d
+    short_window: 6h
+    burn_rate_threshold: <from error_budget_calculator.py>
+    severity: ticket
+
+# Composition with other skills.
+# Wire-up with feature-flags-architect, chaos-engineering, kubernetes-operator
+# is documented in references/composition.md.
+references:
+  monitoring_dashboard: <URL>
+  policy_doc: <URL>
+  related_slos:
+    - <other-slo-id>

package/engineering/skills/slo-architect/references/composition.md

@@ -0,0 +1,139 @@
+# Composition with the rest of the portfolio
+
+`slo-architect` is the keystone. Three other skills in this library already lean on the SLO + error budget concept. This page shows how to wire them together for a coherent reliability stack.
+
+## The unified concept: error budget
+
+```
+┌────────────────────────────────────────────────────────────┐
+│                      slo-architect                         │
+│             defines SLO, error budget, burn rate           │
+└──────────┬─────────────────┬────────────────┬─────────────┘
+           │                 │                │
+           ▼                 ▼                ▼
+   feature-flags-      chaos-engineering   kubernetes-
+   architect           (blast-radius        operator
+   (rollout abort)     bound by EB)         (cap level L4)
+```
+
+## With feature-flags-architect
+
+`feature-flags-architect` defines kill switches. Their abort triggers should reference SLO burn-rate, not arbitrary thresholds.
+
+Before:
+```
+abort_if: "p99 > 1000ms OR error_rate > 1%"
+```
+
+After (SLO-driven):
+```
+abort_if: "burn_rate.fast > 14.4 over 1h (per SLO checkout-success)"
+```
+
+Wire-up:
+
+1. Define SLO via `slo_designer.py`
+2. Run `error_budget_calculator.py` to get the burn-rate threshold
+3. Use that threshold in the flag's abort criteria
+4. The kill_switch_audit.py from feature-flags-architect now has a real signal to verify against
+
+## With chaos-engineering
+
+`chaos-engineering`'s `blast_radius_calculator.py` already takes monthly error budget as input — but the budget should come from the SLO, not be made up.
+
+```bash
+# 1. Get the budget from the SLO definition
+python slo_architect/scripts/error_budget_calculator.py \
+  --target 99.9 --window-days 30 --format json \
+  | jq .budget_minutes
+
+# 2. Pass it to the chaos blast-radius calculator
+python chaos_engineering/scripts/blast_radius_calculator.py \
+  --traffic-share 0.05 \
+  --user-pop 1000000 \
+  --duration-min 15 \
+  --monthly-budget-min 43.2  # ← from step 1
+```
+
+Now blast radius is bounded by REAL error budget, not a number someone typed in.
+
+## With kubernetes-operator
+
+OperatorHub Capability Level 4 ("Deep Insights") requires:
+- `/metrics` endpoint
+- Prometheus alert rules
+- SLOs documented for the operator's managed resources
+
+`slo-architect` provides the SLO definitions; `error_budget_calculator.py` provides the alert rules. Drop them in the operator's Helm chart or OperatorHub bundle.
+
+## End-to-end example
+
+Goal: ship a new checkout flow.
+
+1. **Define the SLO** (slo-architect):
+   ```bash
+   slo_designer.py --service checkout-svc --sli-type request-success-rate \
+     --target 99.9 --window-days 28 --owner team-checkout
+   ```
+
+2. **Compute burn-rate alerts** (slo-architect):
+   ```bash
+   error_budget_calculator.py --target 99.9 --window-days 28
+   # → fast_burn threshold = 14.4
+   ```
+
+3. **Define rollout** (feature-flags-architect):
+   ```bash
+   rollout_planner.py --population 100000 --target-percent 100 \
+     --duration-days 14 --strategy ring
+   # 1% → 5% → 25% → 50% → 100%
+   ```
+
+4. **Wire the abort** (feature-flags-architect):
+   ```yaml
+   abort_if: "burn_rate.fast > 14.4 (per SLO slo-checkout-svc-...)"
+   ```
+
+5. **Validate via chaos** before going wide (chaos-engineering):
+   ```bash
+   blast_radius_calculator.py --traffic-share 0.05 --user-pop 100000 \
+     --duration-min 15 --monthly-budget-min 40.32
+   # → GREEN if <1% of monthly budget
+   ```
+
+6. **Audit the operator** if the service is operator-managed (kubernetes-operator):
+   ```bash
+   operator_capability_audit.py --operator-dir ./checkout-operator
+   # → confirm L4 includes the new SLO
+   ```
+
+Each step uses the previous step's output as input. The SLO is the unifying number.
+
+## What slo-architect does NOT replace
+
+- **observability-designer** — broader observability strategy (metrics, logs, traces, dashboards beyond SLO)
+- **incident-response** — SLO violation may trigger an incident, but incident response is a separate discipline
+- **performance-profiler** — capacity planning needs different metrics than SLO does
+
+Use slo-architect for SLO+error-budget; use the others for their specific scopes.
+
+## Anti-pattern: SLO without composition
+
+A team defines SLOs in a spreadsheet. Nobody references them in:
+- Feature flag rollouts
+- Chaos experiment design
+- Operator capability audits
+- Incident postmortems
+
+The SLOs become a reporting artifact, not an operating tool. The composition story is what makes SLOs change behavior.
+
+## Operational checklist
+
+For any service with a new SLO, verify:
+
+- [ ] SLO defined via `slo_designer.py` (`slo_review.py` passes)
+- [ ] Burn-rate alerts deployed via `error_budget_calculator.py` output
+- [ ] If using feature flags: rollout abort references the SLO burn-rate threshold
+- [ ] If running chaos: blast radius bounded by SLO error budget
+- [ ] If operator-managed: operator audit confirms L4 includes the SLO
+- [ ] Postmortem template (when SLO violated) includes "SLO revision needed?" question

package/engineering/skills/slo-architect/references/error_budget.md

@@ -0,0 +1,128 @@
+# Error budget
+
+The most important number in your SLO.
+
+## Computation
+
+```
+error_budget_fraction = 1 − (target_percent / 100)
+error_budget_minutes  = error_budget_fraction × window_days × 24 × 60
+error_budget_requests = error_budget_fraction × total_requests_in_window
+```
+
+## Reference table
+
+| SLO target | 7-day budget (min) | 28-day budget (min) | 30-day budget (min) | 90-day budget (min) |
+|---|---|---|---|---|
+| 99% | 100.8 | 403.2 | 432 | 1296 |
+| 99.5% | 50.4 | 201.6 | 216 | 648 |
+| 99.9% | 10.08 | 40.32 | 43.2 | 129.6 |
+| 99.95% | 5.04 | 20.16 | 21.6 | 64.8 |
+| 99.99% | 1.008 | 4.032 | 4.32 | 12.96 |
+| 99.999% | 0.1008 | 0.4032 | 0.432 | 1.296 |
+
+99.999% over 30 days = 26 seconds of allowed downtime. Sustainable only with multi-region, sub-second failover, dedicated SRE team.
+
+## Burn-rate alerts (Google SRE Workbook canon)
+
+The single most useful artifact this skill produces. From Chapter 5: "Alerting on SLOs."
+
+### Why multi-window
+
+Single-window alerts fail in opposite directions:
+
+| Window | Failure mode |
+|---|---|
+| 5 minutes | Fires on every blip; alert fatigue |
+| 30 days | Fires when budget is already exhausted; too late |
+| 1 hour alone | Fires too often; misses sustained slow burn |
+
+Multi-window combines:
+- **Long window** filters noise
+- **Short window** speeds detection
+
+The alert fires only when BOTH windows show high burn. This filters spikes (only short window high) and only fires on sustained burn (both windows high).
+
+### Recommended thresholds
+
+| Alert | Long window | Short window | Burn rate threshold | % budget at fire | Severity |
+|---|---|---|---|---|---|
+| Fast burn | 1h | 5m | 14.4 | 2% in 1h | page |
+| Slow burn | 6h | 30m | 6 | 5% in 6h | page |
+| Ticket | 3d | 6h | 1 | 10% in 3d | ticket |
+
+The numbers come from: `burn_rate × bad_event_rate > slo_target_violation_rate`.
+
+`error_budget_calculator.py` computes these for any target+window. Output is PromQL-shaped:
+
+```promql
+# fast_burn (page)
+# Burn rate threshold: 14.4
+(
+  sli:rate1h > 14.4 * (1 - 0.999)
+  AND
+  sli:rate5m > 14.4 * (1 - 0.999)
+)
+```
+
+Paste into your Prometheus rules; adjust label selectors to match your environment.
+
+## Error budget policy
+
+A policy without consequences is theater. The policy says: **"When budget is in state X, action Y happens automatically."**
+
+### Standard 4-state policy
+
+| State | Trigger | Action |
+|---|---|---|
+| **Healthy** | >50% budget remaining | Normal operation; ship features, run experiments |
+| **Caution** | 25-50% budget remaining | Reduce risk on changes; no chaos experiments |
+| **Critical** | <25% remaining | Freeze risky deploys; reliability work prioritized |
+| **Violated** | Budget exhausted | Postmortem; SLO revision; blameless review |
+
+### What "freeze" means
+
+Specifically:
+- No deploys to production except for SLO-improving fixes
+- All releases require explicit owner sign-off
+- Chaos experiments paused
+- Feature flag rollouts paused
+
+This is real, not aspirational. Engineering teams that don't follow through erode the credibility of the SLO.
+
+### Recovery path
+
+After SLO is violated:
+1. Same-day: stop bleeding (rollback, kill switch, scale up)
+2. Within 48h: postmortem published
+3. Within 14 days: at least one follow-up action shipped
+4. At 30 days: review whether SLO is still right
+
+If burns are frequent, the SLO is wrong (too tight) OR the system needs investment.
+
+## Burn-rate vs uptime alerting
+
+Old-school: "Page if any 5xx rate >5%."
+New-school: "Page if budget burns 14.4× faster than sustainable."
+
+Why burn-rate is better:
+- Stays calibrated as traffic grows (5% of low traffic = noise; of high traffic = real)
+- Auto-adjusts for SLO target (99.99% needs sharper alerts than 99%)
+- Aligns alerts with the SLO they protect
+
+## When to skip burn-rate alerts
+
+- For SLOs that aren't "always on" (batch jobs, async pipelines) — measure SLI per execution instead
+- For SLOs in development (no historical data yet)
+- For internal tools where ticket-only is enough — don't page the team for non-paging issues
+
+## The error budget conversation
+
+The SLO + error budget is meant to enable a conversation, not replace it.
+
+> Engineering: "We want to ship the new payment provider this sprint."
+> SRE: "We're at 35% budget remaining for the month. If this rolls back twice, we'll exhaust it."
+> Eng: "Fine, we'll ship behind a feature flag and ramp 1% → 5% → 50% with a 24-hour bake at each stage."
+> SRE: "OK. Set the flag's auto-abort to fire on the burn-rate alert."
+
+That's the conversation the SLO + budget enables. Without numbers, both sides argue from gut feel.