Distributed Systems Testing Skills

---
name: designing-distributed-system-tests
description: Use when designing a test plan for a distributed or stateful system — anything with persistence, replication, consensus, retries, idempotency, async messaging, multi-tenancy, or partial failure. Plans are claim-driven: investigate the product's claimed guarantees first, then design hypotheses and scenarios that try to falsify those claims under fault. Handles change-scoped plans (a commit / PR / feature) and project-wide plans (holistic, with existing-test inventory and gap analysis). Also use when asked to write a stability plan, fault matrix, release-validation plan, durability / partition / upgrade / crash-recovery / linearizability / deterministic-simulation plan, tenant isolation / authz / boundary plan, namespace isolation plan, fairness / noisy-neighbor plan, "what should we be testing", or "make a holistic test plan". Trigger even if the user just says "what should we test for this change", "are my tenants actually isolated", or "how do I test fairness across tenants / shards / queues".
---

# Designing Distributed-System Tests

The default for testing distributed and stateful systems — write a few
integration tests and call it done — finds a small fraction of the bugs
that actually break these systems in production. This skill enforces an
opinionated workflow: scope the change, generate failure-mode hypotheses
that cover the categories the literature says matter most, pick
techniques from a curated catalog, and emit a structured plan file that
the executing-distributed-system-tests skill (or a human) can run.

## Plan modes

This skill produces two shapes of plan. Decide which one applies before
you start; the steps below branch on it.

- **Change-scoped** — the default. Use when the caller names a commit,
  PR, branch-diff, or feature. The plan covers what *this change* could
  regress, scoped by its blast radius.
- **Project-wide** — use when the caller asks for a "release-validation
  plan", "stability plan for the whole system", "test plan to enough
  coverage", "what should we be testing", or otherwise frames the
  request without a specific change. The plan covers what *the system*
  should be tested for, with an explicit inventory of existing tests
  and a gap analysis driving the new-scenario list.

If the framing is ambiguous, ask once before starting — the modes
diverge enough that retrofitting one into the other wastes work.

## Process

Follow these steps in order. Do not skip; the order matters because
later steps depend on artifacts the earlier steps produce.

### 1. Scope the system