distributed-consensus-design
Skill0 starsChanged 5 months agoMITView on GitHub
Reasons about agreement, replication, and coordination across unreliable nodes, choosing the weakest consensus mechanism that satisfies the requirement. Use when designing replicated state, leader election, distributed locks, exactly-once semantics, or evaluating consistency vs availability tradeoffs.
We split this skill into the rules it gives an agent
3 rules. About 0 are common, 3 are distinctive, and 0 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈3
Distinctive · estimate
This author's own choices. Worth a look.
0
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 12
FLP: no deterministic consensus with even one faulty node in a fully async system.
- Distinctive: line 14
Coordination avoidance: if operations commute or can be made conflict-free (CRDTs), you may need no consensus at all.
- Distinctive: line 30
Clock skew: never order events by wall clock across nodes.
≈ “Common” is an estimate: at least 1 in 5 of the 308,232 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Distributed Consensus Design
Consensus is expensive; most systems pay for it without needing it. The skill is identifying the minimum coordination required, because every quorum round-trip is latency you cannot remove.
Start from the impossibility results, not the frameworks
- FLP: no deterministic consensus with even one faulty node in a fully async system. Real systems escape via timeouts/randomization — meaning your liveness depends on timing assumptions that will be violated.
- CAP is a false trilemma at runtime: during a partition you choose C or A; with no partition you have both. The real axis is PACELC — Else, Latency vs Consistency — which governs the 99.9% of time with no partition.
- Coordination avoidance: if operations commute or can be made conflict-free (CRDTs), you may need no consensus at all. Check this first.
Pick the weakest sufficient primitive
Ordered from cheap to expensive — stop at the first that meets the requirement:
- No coordination — immutable data, idempotent writes, CRDTs, last-writer-wins where safe.
- Causal consistency — preserves cause→effect ordering; available under partition.
- Single-leader replication — total order via one writer; cheap reads, failover cost on leader loss.
- Quorum consensus (Raft/Paxos) — linearizable; survives minority failure; pays 1+ round-trips per decision.
- Atomic commit (2PC/3PC) — cross-shard atomicity; blocks on coordinator failure (2PC) — usually wrong for high availability.
Adversarial validation
- Network is unreliable: messages drop, duplicate, reorder, and arrive arbitrarily late. Design for "delayed", not "lost" — a late message can arrive after you assumed it dead.
- Split brain: two nodes both believe they're leader. Does a stale leader's write get accepted? Fencing tokens / epoch numbers are mandatory, not optional.
- Clock skew: never order events by wall clock across nodes. Use logical/hybrid logical clocks; "synchronized NTP" drifts and jumps.
- The exactly-once myth: networks give at-most-once or at-least-once. "Exactly-once" only exists as at-least-once delivery + idempotent processing. Design idempotency keys, not magic.
Non-obvious risks
- A distributed lock without a fencing token does not provide mutual exclusion — the lock holder can pause (GC, VM migration) past the lease and corrupt state.
- Quorum reads/writes (W+R>N) give freshness but not linearizability without read-repair/leases.
- Adding nodes increases availability of reads but the coordination cost and failure surface of writes.
Output structure
Deliver: the exact consistency requirement (per operation, not per system), the weakest primitive that satisfies it with justification, the partition behavior (what's sacrificed and when), the fencing/idempotency mechanism, and the failure scenario (leader loss, partition, slow node) walked through to a safe outcome.
In this repository29 other files it gives its agents.
- adversarial-code-reviewSkill
- api-contract-designSkill
- attack-surface-mappingSkill
- authn-authz-design-reviewSkill
- benchmark-designSkill
- capacity-scalability-planningSkill
- concurrency-race-analysisSkill
- data-consistency-modelingSkill
- data-exfiltration-analysisSkill
- error-handling-architectureSkill
- event-driven-architectureSkill
- experiment-designSkill
- hypothesis-falsificationSkill
- incident-rca-postmortemSkill
- legacy-refactoring-strategySkill
- literature-synthesisSkill
- metrics-designSkill
- multi-layer-caching-strategySkill
- mvp-scope-cuttingSkill
- performance-profilingSkill
- rate-limiting-designSkill
- requirements-disambiguationSkill
- secrets-management-auditSkill
- statistical-validity-analysisSkill
- supply-chain-risk-analysisSkill
- system-decomposition-synthesisSkill
- threat-modelingSkill
- tradeoff-decision-frameworkSkill
- user-failure-mode-mappingSkill
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

