| name | distributed-systems-checklist |
| description | Audit distributed services against the 8 fallacies and the CAP trade-off. Use during design review for any service that crosses a network boundary, during incident triage when root cause is unclear and a network or IPC layer is involved, or when drafting an architectural ADR for new distributed components. |
| license | MIT |
Distributed Systems Checklist
Surface unstated assumptions in distributed-system designs and incidents.
When to Use
Fires specifically when a network / IPC boundary is in play — the 8
fallacies, CAP trade-offs, partial failure. Single-process layering questions
are clean-architecture-guide, and the operational "is it ready for
production" gate (SLOs, runbooks, rollout) is reliability-checklist. This
skill is about the correctness of crossing the wire, not the layering behind
it or the ops in front of it.
Fallacies Checklist
For each, state the assumption made and the mitigation in place. Mark N/A only with explicit justification.
- The network is reliable: retries, circuit breakers, idempotency keys, deadlines.
- Latency is zero: budget per call, p99 target, async where viable, batch I/O.
- Bandwidth is infinite: payload size limits, compression, pagination, streaming for large data.
- The network is secure: mTLS, authn/authz at every hop, no plaintext credentials in transit.
- Topology doesn't change: service discovery, no hard-coded IPs/hosts, graceful re-resolution.
- There is one administrator: explicit ownership, runbook, on-call mapping per component.
- Transport cost is zero: cost-aware design (egress, cross-AZ), measured not assumed.
- The network is homogeneous: protocol/version negotiation, no implicit "all clients are v2".
CAP Trade-off
Document for every distributed datastore/coordinator: which two of {Consistency, Availability, Partition tolerance} the system guarantees, and what behavior occurs under partition. No "we have all three".
Completion
- 8 fallacies — each has
assumption + mitigation (or justified N/A)
- CAP statement — written, with partition behavior
- Findings appended to design ADR or incident retrospective
Anti-Patterns
- Rubber-stamp "we use HTTP, so it's fine" without listing concrete mitigations
- Skipping CAP analysis because the system "feels eventually consistent"
- Treating the checklist as a one-time gate instead of a re-verification on every topology change
