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
lastX field into one state.json is still shared mutation. indexer-state.json + metrics-state.json is 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.
This repository (Asymmetric-al/core)
Vendored from p3-stack (MIT) at commit 09909eb. Provenance is in references/upstream.md. On conflict, the current user request, root AGENTS.md, the nearest nested AGENTS.md, and the matching docs/ai/rules/* rulebook win over this skill.
- Explicit invocation only: use it when the user invokes
/principle-separate-before-serializing-shared-state (Claude Code, Cursor, T3 Code) or $principle-separate-before-serializing-shared-state (Codex), or when an invoked p3-stack skill routes here. Do not route other work to it.
- Confirm before outward-facing or hard-to-reverse actions such as pushing, merging, deploying, deleting, or posting messages, unless the user authorized that action for this task.
Edit this canonical copy in docs/ai/skills/principle-separate-before-serializing-shared-state/, then run bun run skills:sync and bun run skills:verify.
1---2name: principle-separate-before-serializing-shared-state3description: "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."4disable-model-invocation: true5metadata:6 source: https://skillmd.com/skills/asymmetric-al/principle-separate-before-serializing-shared-state7---89# Separate Before Serializing Shared State1011When 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.1213**Why:** Concurrent writes to shared state create race conditions that are intermittent, hard to reproduce, and expensive to debug.1415**Pattern:**16171. **Identify shared mutable state** (files both read and write, branches both push to, APIs both define and consume).182. **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 `lastX` field into one `state.json` is still shared mutation. `indexer-state.json` + `metrics-state.json` is not.193. **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.2021<!-- CORE-OVERLAY-START -->2223## This repository (Asymmetric-al/core)2425Vendored from [p3-stack](https://github.com/uzairansaruzi/p3-stack) (MIT) at commit `09909eb`. Provenance is in `references/upstream.md`. On conflict, the current user request, root `AGENTS.md`, the nearest nested `AGENTS.md`, and the matching `docs/ai/rules/*` rulebook win over this skill.2627- Explicit invocation only: use it when the user invokes `/principle-separate-before-serializing-shared-state` (Claude Code, Cursor, T3 Code) or `$principle-separate-before-serializing-shared-state` (Codex), or when an invoked p3-stack skill routes here. Do not route other work to it.28- Confirm before outward-facing or hard-to-reverse actions such as pushing, merging, deploying, deleting, or posting messages, unless the user authorized that action for this task.2930Edit this canonical copy in `docs/ai/skills/principle-separate-before-serializing-shared-state/`, then run `bun run skills:sync` and `bun run skills:verify`.3132<!-- CORE-OVERLAY-END -->