mirror of https://github.com/alirezarezvani/claude-skills.git synced 2026-08-28 04:24:58 +00:00

feat(skills): ship chaos-engineering (Phase 3 — resilience testing discipline)

Phase 3 of the multi-skill build effort. Same 14-step pipeline. Composes
explicitly with feature-flags-architect (kill switches as abort triggers)
and kubernetes-operator (operators are common chaos targets).

## What landed

### New skill: engineering/chaos-engineering

End-to-end chaos engineering discipline. Published as BOTH:
- Standalone plugin: engineering/chaos-engineering/
- Bundled mirror:    engineering/skills/chaos-engineering/

3 stdlib-only Python tools (Karpathy complexity 95/100 — best in portfolio):
- experiment_designer.py        — generates structured plans with hypothesis,
                                   steady-state, blast radius, abort criteria,
                                   rollback. Refuses to render plans without
                                   abort criteria (exit code 1).
- blast_radius_calculator.py    — computes affected users + error budget
                                   consumption + GREEN/YELLOW/RED risk score.
                                   Validates inputs (0 ≤ traffic-share ≤ 1).
- experiment_postmortem.py      — blameless postmortems from plan + result log;
                                   detects blame-laden language ("fault of",
                                   "should have known", "stupid", etc.) and
                                   warns at write time.

4 reference docs:
- chaos_principles.md      — 4 founding principles + 5th abort principle,
                              maturity model, history, when-to-start checklist
- experiment_design.md      — 7-section plan structure, pre-flight checklist,
                              time-boxing, escalation
- attack_taxonomy.md        — 7 attack types (latency / error / resource /
                              network-partition / dependency-failure / time-skew
                              / infrastructure) with magnitudes and tooling
- tooling_landscape.md      — Chaos Toolkit / Mesh / Litmus / Gremlin / AWS FIS
                              / DIY decision tree

Templates:
- experiment_template.md    — fill-in plan with all 7 sections
- postmortem_template.md    — blameless postmortem structure

Plus: SKILL.md (213 lines), README.md, /chaos-experiment slash command.

### Audit verdict (evidence-based)

Closest existing skills:
- engineering-team/incident-response — for actual incidents, not prevention
- engineering-team/red-team — adversarial; different goal (find attack paths)
- engineering-team/threat-detection — hunting; different goal
- engineering/observability-designer — measurement, not fault injection
None cover the chaos-engineering discipline (hypothesis-driven fault injection
with bounded blast radius). Verdict: BUILD. Gap is real and tooling-shaped.

### Composition story (Phase 1+2+3 form a stack)

```
feature-flags-architect.kill_switch_audit.py
  ↓ defines kill switches that ↓
chaos-engineering.experiment_designer.py
  ↓ designs experiments against ↓
kubernetes-operator (and other targets)
```

Together: a complete progressive-delivery + resilience-testing stack.

### Marketplace / registry

- marketplace.json: chaos-engineering registered as standalone plugin
- engineering-advanced-skills bundle: 47 → 48 skills, version → 2.4.2
- engineering/.claude-plugin/plugin.json: version + skill list updated
- mkdocs.yml: nav entry under "Engineering - POWERFUL"
- docs/skills/engineering/chaos-engineering.md: docs page (manual,
  pending generate-docs.py classification fix)
- docs/commands/chaos-experiment.md: auto-generated
- .codex/, .gemini/: synced

### Karpathy-coder gates

- complexity_checker (strict): 95/100 average — BEST score in the new
  portfolio. Only 1 WARN (depth 5 in blast_radius_calculator.py validation
  branches; the other 2 scripts hit no findings whatsoever).
- All 1666 tests pass (was 1648; added 18 for the new skill).
- mkdocs build --strict: succeeded in 13.33s.

### 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 by check_plugin_json.py)
✓  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/           → 1666 passed, 0 failed
✓  CHANGELOG.md            → [Unreleased] entry expanded for Phase 3
✓  Self-test (RED case)    → 50% blast radius on 99.9% baseline correctly
                             classifies as RED (17.33% of monthly budget) and
                             returns ABORT recommendation
✓  Composition test        → references named skills explicitly compose

## Phase 1+2+3 cumulative

- 3 new skills: feature-flags-architect, kubernetes-operator, chaos-engineering
- 9 new Python tools (all stdlib, all <200 LOC, average complexity 90/100)
- 12 new reference docs (~250-500 lines each)
- 3 new slash commands (/flag-cleanup, /operator-audit, /chaos-experiment)
- 2 repo-infrastructure scripts (sync_skill_bundles, check_plugin_json)
- 1 pre-existing test fix (full-page-screenshot CI red)

## Files

- engineering/chaos-engineering/                                (new standalone plugin)
- engineering/skills/chaos-engineering/                         (new bundled mirror)
- commands/chaos-experiment.md                                  (new slash command)
- docs/skills/engineering/chaos-engineering.md                  (new docs page)
- docs/commands/chaos-experiment.md                             (auto-generated)
- mkdocs.yml                                                    (nav entries)
- .claude-plugin/marketplace.json                               (registered)
- engineering/.claude-plugin/plugin.json                        (bundle bumped)
- CHANGELOG.md                                                  ([Unreleased] expanded)
- .codex/, .gemini/                                             (cross-tool sync)

https://claude.ai/code/session_01Dq12xJakFRxwaoU8Pqejdm

2026-05-09 21:24:16 +00:00

3.6 KiB

Raw Permalink Blame History

Chaos Engineering

End-to-end discipline for chaos experiments — design, run, learn — without becoming an outage.

What's inside

3 stdlib Python tools — experiment designer, blast-radius calculator, postmortem generator
4 reference docs — principles, experiment design, attack taxonomy, tooling landscape
2 templates — experiment plan, postmortem
/chaos-experiment slash command — interactive design wizard

Install

# Via Claude Code marketplace
/plugin install chaos-engineering

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

Quick start

SKILL=engineering/chaos-engineering/skills/chaos-engineering

# 1. Design an experiment
python "$SKILL/scripts/experiment_designer.py" \
  --target checkout-svc \
  --hypothesis "p99 < 500ms when payment slows" \
  --attack latency --magnitude "+200ms" \
  --abort-if "p99 > 1000ms OR error_rate > +1pp"

# 2. Calculate blast radius
python "$SKILL/scripts/blast_radius_calculator.py" \
  --traffic-share 0.05 --user-pop 1000000 \
  --duration-min 15

# 3. Generate postmortem after running
python "$SKILL/scripts/experiment_postmortem.py" \
  --plan plan.json --result-log results.txt

Key principles

Build a hypothesis around steady-state behavior — measurable, falsifiable
Vary real-world events — realistic failures only, not astronomy-grade
Run experiments in production — staging never has prod failure modes
Automate experiments to run continuously — single experiment = press release; continuous = engineering
Define abort criteria up front — chaos without abort = outage

The 7 attack types

Attack	Tests	Magnitude examples
Latency	Timeouts, retries, circuit breakers	+200ms, +2s
Error	Error handling, fallback paths	1%, 50%, 100%
Resource	Saturation, autoscaling, OOM	80% CPU, 90% memory, fill /var
Network partition	Consensus, leader election, failover	drop 100% to peer X
Dependency failure	Graceful degradation	timeout 100% to dep X
Time skew	Clocks, TTLs, retry backoff	+5min, +1day
Infrastructure	Auto-recovery, replica maintenance	kill 1 of N

Composition with other skills

Skill	Composition
`feature-flags-architect`	Kill switches there are abort triggers here
`kubernetes-operator`	Operators are common chaos targets
`incident-response`	Chaos that escalates becomes an incident

Skill structure

chaos-engineering/
├── README.md
├── .claude-plugin/plugin.json
└── skills/chaos-engineering/
    ├── SKILL.md
    ├── scripts/
    │   ├── experiment_designer.py
    │   ├── blast_radius_calculator.py
    │   └── experiment_postmortem.py
    ├── references/
    │   ├── chaos_principles.md
    │   ├── experiment_design.md
    │   ├── attack_taxonomy.md
    │   └── tooling_landscape.md
    └── assets/
        ├── experiment_template.md
        └── postmortem_template.md

Verifiable success

A team using this skill should achieve:

100% of chaos experiments have written hypothesis, abort criteria, blast-radius calc
Blast radius for any single experiment ≤10% of monthly error budget
Mean time between chaos experiments <14 days (continuous, not one-off)
Each experiment produces ≥1 follow-up action that gets shipped
No chaos experiment escalates to a customer-impacting incident in trailing 90 days

License

MIT — see repo root LICENSE.

3.6 KiB Raw Permalink Blame History