mirror of https://github.com/alirezarezvani/claude-skills.git synced 2026-08-28 04:24:58 +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

2 KiB

Raw Blame History

description
Interactive wizard to design an SLO with SLI, target, error budget, and burn-rate alerts

/slo-design

Step through SLO design using the slo-architect skill. Produces an SLO definition, computes error budget + multi-window burn-rate alerts, and runs the reviewer to catch common bugs.

Usage

/slo-design
/slo-design --service checkout-svc --sli-type request-success-rate --target 99.9

Implementation

SKILL=engineering/slo-architect/skills/slo-architect

# Step 1: gather inputs (service, sli-type, target, window, owner)
# Step 2: render SLO definition
python "$SKILL/scripts/slo_designer.py" \
  --service "$SERVICE" \
  --sli-type "$SLI_TYPE" \
  --target "$TARGET" \
  --window-days "$WINDOW_DAYS" \
  --owner "$OWNER" \
  --policy-doc "$POLICY_DOC" \
  --format json > .slo.json

# Step 3: compute error budget + burn-rate alerts
python "$SKILL/scripts/error_budget_calculator.py" \
  --target "$TARGET" \
  --window-days "$WINDOW_DAYS"

# Step 4: render the markdown SLO for peer review
python "$SKILL/scripts/slo_designer.py" \
  --service "$SERVICE" \
  --sli-type "$SLI_TYPE" \
  --target "$TARGET" \
  --window-days "$WINDOW_DAYS" \
  --owner "$OWNER" \
  --policy-doc "$POLICY_DOC"

# Step 5: validate against the reviewer
echo "=== After saving the SLO, run slo_review.py against the doc ==="

Output

A markdown SLO definition with:

Service, owner, user journey
SLI type with numerator/denominator expressions
Target, window, error budget
Multi-window burn-rate alert thresholds (PromQL-shaped)
Review cadence

Pre-conditions

slo-architect skill installed
Service identified
30 days of historical SLI data available (to pick a sustainable target)
Error budget policy doc exists or will be created

Post-conditions

.slo.json written for use with downstream tools (chaos-engineering blast radius, etc.)
Markdown SLO streamed for review
Recommendation printed: PASS / WARN / FAIL on slo_review.py checks

2 KiB Raw Blame History