principle-separate-before-serializing-shared-state
cursor/plugins
Eliminate concurrent write conflicts by separating mutable state before applying serialization.
What is principle-separate-before-serializing-shared-state?
This principle guides you to avoid race conditions in concurrent systems by first eliminating shared mutable state between actors, and only applying structural serialization (locks, sequential phases, atomic operations) when sharing is truly unavoidable. Use it when multiple processes or threads might write to the same file, branch, key, or state object.
- Identify shared mutable state across concurrent actors (files, branches, API definitions, state objects)
- Separate write targets so each actor owns its own state and publishes independent facts
- Apply structural serialization only when one shared write target is a genuine invariant
- Distinguish between true shared mutation and independent state that can be merged at read boundaries
How to install principle-separate-before-serializing-shared-state
npx skills add https://github.com/cursor/plugins --skill principle-separate-before-serializing-shared-stateHow to use principle-separate-before-serializing-shared-state
- 1.Identify all mutable state that concurrent actors read or write
- 2.Map which actors write to the same target (file, branch, key, or object)
- 3.For each shared target, ask whether all actors truly need one canonical object or are publishing independent facts
- 4.Separate write targets by actor (e.g., separate state files per worker) when possible
- 5.Only when sharing is unavoidable, enforce serialization structurally via lockfiles, sequential phases, single-writer patterns, or atomic operations
Use cases
- Preventing race conditions when multiple workers write to the same state file
- Refactoring shared JSON state into per-actor files that merge at reporting time
- Designing multi-branch CI/CD pipelines where each actor pushes to its own branch
- Ensuring atomic updates in distributed systems by eliminating unnecessary shared write targets
- Backend engineers designing concurrent systems
- DevOps and infrastructure teams managing multi-worker deployments
- Distributed systems architects
- Teams debugging intermittent race conditions
principle-separate-before-serializing-shared-state FAQ
Only when one shared write target is a genuine invariant—i.e., the system truly requires a single canonical object. Treat the need for a lock as a design smell; first verify that separation is not possible.
Shared mutation is when multiple actors write to the same object (e.g., two workers both updating fields in one state.json). Independent state is when each actor owns its own file or key; merging happens only at read/reporting boundaries.
Merge at the read or reporting boundary, not at the write boundary. Each actor writes to its own owned file or key; a coordinator or aggregator reads all of them when needed.
No. Conventions and instructions are not concurrency control and will fail under load or timing variations. Use structural mechanisms: lockfiles, sequential phases, exclusive ownership, or atomic operations.
A real invariant is when the system logically requires one canonical source of truth that all actors must read and write. Most cases are not true invariants; they just appear that way until you redesign for separation.
Full instructions (SKILL.md)
Source of truth, from cursor/plugins.
name: principle-separate-before-serializing-shared-state description: "Apply when concurrent actors might write to the same file, branch, key, or state object. Eliminate the sharing first; serialize structurally only when one shared writer is a real invariant." disable-model-invocation: true
Separate Before Serializing Shared State
When concurrent actors might share mutable state, first ask whether they need the same mutable object. If not, eliminate the sharing. When sharing is real, enforce serialization structurally: lockfiles, sequential phases, exclusive ownership. Instructions and conventions are not concurrency control.
Why: Concurrent writes to shared state create race conditions that are intermittent, hard to reproduce, and expensive to debug.
Pattern:
- Identify shared mutable state (files both read and write, branches both push to, APIs both define and consume).
- Default: eliminate the shared write target. Ask: do these actors need one canonical object, or are they publishing independent facts? Give each actor its own owned file, key, branch, or state directory, and merge only at the read/reporting boundary. Two workers writing their own
lastXfield into onestate.jsonis still shared mutation.indexer-state.json+metrics-state.jsonis not. - Only when one shared write target is a real invariant, serialize access structurally (lockfiles, sequential phases, single-writer actor, or atomic compare-and-swap). Treat "we need a lock" as a design smell to check, not as the default answer.
Related skills
More from cursor/plugins and the wider catalog.
principle-sequence-verifiable-units
Break multi-step work into small verifiable units, sequence commits to prove the logic to reviewers.
principle-subtract-before-you-add
Remove complexity first—delete dead code and redundancy before adding features or refactoring.
principle-type-system-discipline
Apply type-system discipline to eliminate impossible states and catch bugs at compile time.
recall
Reconstruct your recent working context from chat history and shared records to resume work efficiently.
reflect
Mine conversations for durable learnings and route them into skill edits.
review-and-ship
Review code for bugs and intent fit, run tests, and open or update a PR.