distributed-systems-debugging
Skill0 starsChanged 2 months agoMITView on GitHub
Debug failures involving retries, timeouts, partial success, replication, failover, consistency, ordering, recovery, and distributed state. Use when behavior spans services, nodes, regions, or asynchronous boundaries.
In this repository5 other files it gives its agents.
- AGENTS.mdAGENTS.md
- cpp-reliabilitySkill
- incident-responseSkill
- performance-investigationSkill
- pull-requestSkill
The file
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 44
Check duplicate delivery, late completion, stale reads, reordered events, partial persistence, and split ownership.
- Distinctive: line 46
Consider whether local success can hide global failure.
- Distinctive: line 52
Avoid adding coordination unless the invariant requires it.
≈ “Common” is an estimate: at least 1 in 5 of the 350,495 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 systems debugging
Define the invariant
State the property that should always hold, such as:
- An acknowledged write remains durable.
- A request is applied at most once.
- Failover does not expose stale ownership.
- Recovery converges without operator intervention.
Describe the observed counterexample precisely.
Map the flow
Identify:
- State owners and durable stores.
- Control-plane and data-plane paths.
- Synchronous and asynchronous boundaries.
- Retry, timeout, cancellation, and failover behavior.
- Replication, quorum, ordering, and consistency assumptions.
Build an evidence table
For each signal capture:
- Timestamp and clock source.
- Component and correlation identifier.
- Observation.
- Reliability and possible ambiguity.
- Hypotheses supported or contradicted.
Test hypotheses
- Rank hypotheses by explanatory power, not familiarity.
- Design tests that distinguish between leading hypotheses.
- Check duplicate delivery, late completion, stale reads, reordered events, partial persistence, and split ownership.
- Consider whether local success can hide global failure.
Recommend changes
- Restore the invariant at the narrowest responsible boundary.
- Make retries and recovery explicit and observable.
- Avoid adding coordination unless the invariant requires it.
- Include telemetry and regression coverage needed to detect recurrence.
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.