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

2 KiB

Raw Blame History

description
Interactive wizard to design and validate a chaos engineering experiment

/chaos-experiment

Step through the design of a chaos engineering experiment using the chaos-engineering skill. Produces a plan, calculates blast radius, validates abort criteria, and outputs a markdown plan ready for peer review.

Usage

/chaos-experiment
/chaos-experiment --target checkout-svc --attack latency

Implementation

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

# Step 1: gather inputs interactively (target, hypothesis, attack, magnitude, ...)
# Step 2: run experiment_designer.py to produce the plan
python "$SKILL/scripts/experiment_designer.py" \
  --target "$TARGET" --hypothesis "$HYPOTHESIS" \
  --attack "$ATTACK" --magnitude "$MAGNITUDE" \
  --duration-min "$DURATION" \
  --abort-if "$ABORT" --owner "$OWNER" \
  --format json > .chaos-plan.json

# Step 3: calculate blast radius against the team's error budget
python "$SKILL/scripts/blast_radius_calculator.py" \
  --traffic-share "$TRAFFIC_SHARE" \
  --user-pop "$USER_POP" \
  --duration-min "$DURATION" \
  --baseline-availability "$BASELINE_AVAIL" \
  --expected-impact-availability "$IMPACT_AVAIL"

# Step 4: render the markdown plan for peer review
python "$SKILL/scripts/experiment_designer.py" \
  --target "$TARGET" --hypothesis "$HYPOTHESIS" \
  --attack "$ATTACK" --abort-if "$ABORT" --owner "$OWNER"

Output

A markdown plan with:

Hypothesis, steady-state metric, attack, magnitude, duration
Blast radius (calculated) with risk score (GREEN/YELLOW/RED)
Abort criteria parsed from --abort-if
Rollback procedure
Monitoring dashboard link
Learning question

Pre-conditions

chaos-engineering skill installed
Target identified
Steady-state metric and dashboard available
On-call team available
Error budget known (or use defaults)

Post-conditions

.chaos-plan.json written for use with experiment_postmortem.py later
Markdown plan streamed for review
Recommendation printed: PROCEED / REDUCE / ABORT

2 KiB Raw Blame History