holdfast

holdfast

!checklist init ${CLAUDE_SKILL_DIR} --force

A distributed system is a set of independent computers that fail independently, talk over an unreliable asynchronous network, and share no clock and no memory — trying to behave, to the outside, like one reliable machine. Nearly all of its difficulty comes from three enemies: partial failure, the asynchronous, unreliable network, and the absence of a global clock or global state. holdfast is the fixing device you clamp onto a distributed design or distributed code to keep it correct while those enemies are active — because they are always active. It audits (and guides you to build) across gated stages, and it will not advance past a GATE until the checklist tool clears it.

The one mental shift everything hangs on — the third state. On a single machine an operation has two outcomes: success or failure. Cross a network and a third appears: "I don't know." You sent a request and got no reply — did it not arrive? arrive and run slowly? run, but the reply was lost (so it did happen)? did the node die? You cannot tell. "Slow" and "dead" are indistinguishable from the outside, so a timeout is a guess, not a fact. Single-machine code has no branch for "unknown" — and most distributed bugs grow in that missing branch. Every technique in this skill answers one question: given that "I don't know" will happen, what do I do?

The first law, because it governs everything: don't distribute until you must. A single strong machine is dramatically simpler — shared memory, one clock, all-or-nothing failure. You distribute only when forced: data/traffic too big for one box (scale), no single point of failure (availability), users too far (latency), or the problem is inherently multi-site. Everything hard below is the bill for that choice. This is the suite's "by scale and risk, not by fashion" — load-bearing's Monolith-First, aimed at the machine boundary.

The framing that makes failure normal: Richard Cook's How Complex Systems Fail — a complex system runs degraded as its constant background state, disasters are cascades of several aligned failures (no single root cause), and safety is a system-level property, not a component one. In distributed terms that is literal: at any moment some node is slow, some disk dying, some link flapping, and the system serves anyway because it was built to tolerate that. So fault tolerance is not a feature you add — it is the floor.

Discipline: finish every GATE before the next stage. GATEs are hard — never skip, batch past, or self-certify a stage you have not done. The checklist tool enforces the order; let it. Commands address stages by name.

Speak the user's language. Most calls here are trade-offs the user owns (is this consistency level worth the latency, is this duplication-on-retry acceptable, do we actually need to distribute this). Read their fluency and gloss a term on first use (the third state, idempotency, at-least-once, partial order, causality, backoff/jitter, circuit breaker). A "finding" the user can't evaluate is an opinion imposed, not a judgment shared.

Read references/the-three-enemies.md first — the must-be-told foundation: the three enemies, the third state, the fallacies a single-machine programmer carries over, and why "failure is the background." It is the key that makes every later stage derivable rather than memorized.