mirror of https://github.com/alirezarezvani/claude-skills.git synced 2026-09-07 08:26:02 +00:00

Alireza Rezvani 9dd6fd184c

feat(slo-architect): Phase 4 — SLO/SLI/error-budget discipline (#605 )

Phase 4 of the multi-skill build effort. Same 14-step pipeline.

## What landed

### New skill: engineering/slo-architect

End-to-end SLO discipline per Google SRE Workbook. Published as BOTH:
- Standalone plugin: engineering/slo-architect/
- Bundled mirror:    engineering/skills/slo-architect/

3 stdlib-only Python tools (Karpathy complexity 95/100):
- slo_designer.py             — generates SLO definitions; refuses to render
                                 if required fields missing (owner, policy doc,
                                 SLI numerator/denominator). Supports 5 SLI
                                 types: request-success-rate, request-latency,
                                 availability-time, data-freshness, correctness.
- error_budget_calculator.py  — computes error budget AND the canonical
                                 multi-window burn-rate alert thresholds:
                                 fast (1h/5m, page), slow (6h/30m, page),
                                 ticket (3d/6h). Output is PromQL-shaped,
                                 ready to paste into Prometheus rules.
- slo_review.py               — audits SLO docs for 7 common bugs:
                                 target ≥99.99, target ≤99, window <7d,
                                 window >90d, no SLI definition, no error
                                 budget policy, CPU-as-SLI.

4 reference docs:
- slo_principles.md   — SLI vs SLO vs SLA, Google SRE Workbook canon
- sli_design.md       — 5 SLI types with examples and anti-patterns
- error_budget.md     — error budget math, burn-rate alerts, budget policy
- composition.md      — how SLOs feed feature-flags, chaos, kubernetes-operator

Asset templates:
- slo_template.yaml          — fillable SLO YAML with all required fields
- error_budget_policy.md     — fillable 4-state policy (HEALTHY / CAUTION /
                                CRITICAL / VIOLATED)

Plus: SKILL.md, README.md, /slo-design slash command.

## Composition with prior phases

Explicit wire-up to the rest of the portfolio:
- feature-flags-architect.kill_switch_audit references SLO burn-rate
- chaos-engineering.blast_radius_calculator takes SLO error budget as input
- kubernetes-operator capability level L4 requires SLOs + Prometheus rules

The SLO is the unifying number: rollout abort, chaos blast radius, and
operator capability all reference it. references/composition.md walks
through end-to-end use.

## Audit verdict (evidence-based)

Closest existing skill: engineering/observability-designer covers SLI/SLO as
ONE topic among many (metrics, logs, traces, dashboards, alerting). It has
no dedicated tools and is breadth-not-depth. slo-architect is the focused
SLO discipline with deterministic Python tools — same gap pattern as
kubernetes-operator vs senior-devops.

## Marketplace / registry

- marketplace.json: slo-architect registered as standalone plugin
- engineering-advanced-skills bundle: 49 → 50 skills, version → 2.4.4
- engineering/.claude-plugin/plugin.json: version + skill list updated
- mkdocs.yml: nav entry under "Engineering - POWERFUL"
- docs/skills/engineering/slo-architect.md: docs page (manual)
- docs/commands/slo-design.md: auto-generated
- .codex/, .gemini/: synced

## Karpathy-coder gates

- complexity_checker (strict): 95/100 average — same top score as
  chaos-engineering. 1 WARN (depth 7 in slo_review.py from generator
  expressions). Verdict: WARN, not FAIL.
- All 1689 tests pass (was 1671; +18 for the new skill).
- mkdocs build --strict: succeeded in 12.47s.

## Verifiable success criteria (all green)

✓  scripts/*.py --help     → exit 0 for all 3 scripts
✓  SKILL.md frontmatter    → name + description + tags + compatible_tools
✓  plugin.json schema      → 8 fields exact (verified)
✓  sync_skill_bundles      → standalone ↔ bundled mirror in sync
✓  marketplace.json        → standalone entry + bundle counts updated
✓  generate-docs.py        → command page generated (skill page manual)
✓  mkdocs build --strict   → succeeded
✓  cross-tool sync         → codex + gemini synced
✓  pytest tests/           → 1689 passed, 0 failed
✓  CHANGELOG.md            → [Unreleased] entry expanded for Phase 4
✓  Self-test               → error_budget_calculator on 99.9% / 28d emits
                             correct burn-rate (14.4 fast, 6 slow, 1 ticket)
✓  Composition             → references named skills explicitly compose

## Phase 1+2+3+4 cumulative

- 4 new skills: feature-flags-architect, kubernetes-operator,
                chaos-engineering, slo-architect
- 12 new Python tools (all stdlib, all <250 LOC, average complexity 92/100)
- 16 new reference docs
- 4 new slash commands (/flag-cleanup, /operator-audit, /chaos-experiment,
                        /slo-design)

https://claude.ai/code/session_01Dq12xJakFRxwaoU8Pqejdm

Co-authored-by: Claude <noreply@anthropic.com>

2026-05-10 07:39:05 +02:00

3.2 KiB

Raw Permalink Blame History

SLO Architect

Define SLOs that mean something. Most "SLOs" in the wild are arbitrary numbers nobody believes — 99.9% on every endpoint, no SLI definition, no error budget policy. This skill enforces the Google SRE Workbook discipline.

What's inside

3 stdlib Python tools — SLO designer, error-budget calculator with multi-window burn-rate alerts, SLO reviewer
4 reference docs — principles, SLI design, error budget, composition
2 asset templates — SLO YAML, error budget policy
/slo-design slash command

Install

# Via Claude Code marketplace
/plugin install slo-architect

# Or clone the repo
git clone https://github.com/alirezarezvani/claude-skills.git
cd claude-skills/engineering/slo-architect

Quick start

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 28

# 2. Compute error budget + multi-window burn-rate alerts
python "$SKILL/scripts/error_budget_calculator.py" --target 99.9 --window-days 28

# 3. Review existing SLOs for common bugs
python "$SKILL/scripts/slo_review.py" --slo-doc docs/slos/

Key principles

An SLO is a promise about user experience — not a CPU graph
Pick the SLI from the user's perspective — request-success / latency / availability / freshness / correctness
Pick the target from data — measure 30 days, then floor it
Multi-window burn-rate alerts — single-window is either too noisy or too slow
Error budget without a policy is theater — every SLO ships with a policy

The 5 SLI types

User experience	SLI type
"Did the request succeed?"	request-success-rate
"Was the response fast?"	request-latency
"Was the service up?"	availability-time
"Is the data current?"	data-freshness
"Was the answer correct?"	correctness

Composition with the rest of the portfolio

Skill	Composition
`feature-flags-architect`	Rollout abort criteria reference SLO burn-rate thresholds
`chaos-engineering`	Blast-radius calculator takes monthly error budget as input
`kubernetes-operator`	Operator capability L4 requires SLOs + Prometheus rules

Skill structure

slo-architect/
├── README.md
├── .claude-plugin/plugin.json
└── skills/slo-architect/
    ├── SKILL.md
    ├── scripts/
    │   ├── slo_designer.py
    │   ├── error_budget_calculator.py
    │   └── slo_review.py
    ├── references/
    │   ├── slo_principles.md
    │   ├── sli_design.md
    │   ├── error_budget.md
    │   └── composition.md
    └── assets/
        ├── slo_template.yaml
        └── error_budget_policy.md

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
Mean time to detect SLO violation: <30 min
Quarterly SLO review actually happens

License

MIT — see repo root LICENSE.

3.2 KiB Raw Permalink Blame History