SKILL.md
about 2,300 tokens- pstack
- greenline
---
name: "concurrency"
description: "Decide whether code should be concurrent, reason about a concurrent design by its timelines, separate shared state before serializing it, and make an operation converge when a crash, a restart or a retry runs it twice, an idempotency key derived from the intent and claimed atomically. Use when adding threading, async, goroutines, workers or parallelism; when a race or an ordering bug appears; when two actors may write the same file, key or branch; and when a command, a step or a loop must survive crashes, restarts and retries."
---
concurrency is the habit for the moment code is made concurrent or a race or an ordering bug appears, two actors may write the same state, or an operation must survive a crash, a restart or a retry, at whatever step the work is in, most often build. It writes no record of its own. Concurrency is a floor in AGENTS.md: found before the mode is proposed, it raises the proposal to the mode that floor names, and found later it is reported. Sections 1 to 5 reason about concurrent code; section 6 makes an operation that may run twice converge.
Three questions in order: whether concurrency is warranted, how to reason about the design, and which laws hold whatever the runtime is called. The last two are wasted on a program that failed the first.
## 1. Decide, and the default is no
The burden of proof rests on the concurrency, never on the serial version: three languages agree that "this shiny feature" is where the danger sits (Latour), that many tasks do not need it (Matthews), and that short work loses to the cost of moving values (Bodner).
**Three properties qualify a workload, all of them:** parts doing I/O without interacting, a place where results combine, and a deadline that is a number. For I/O, interleaving pays only where waiting exceeds processing, and splitting a saturated resource degrades. Reason in orders of magnitude, and benchmark only where the order is genuinely unknown. **Decide up front,** since the choice is architectural and dearest after the second consumer. **Write it serially first, then benchmark both ways,** with the serial version as the control: one author's own benchmark refuted his own parallel tool, cheap arithmetic running longer in parallel (Matthews).
## 2. The instrument: draw the timelines
One author's method (Normand): section 1 has three witnesses, while sections 2, 3 and 5 have one, and rung three of section 3 a second, principle-separate-before-serializing-shared-state.
A timeline is a sequence of actions over time, and a diagram draws several side by side, which makes interference visible. Actions in order share a timeline; actions that can run at once or out of order go on separate ones. Calculations are left off, since their results do not depend on when they run, which keeps the diagram usably small. Three steps, and their order defends against drawing the diagram you already believe: identify the actions, draw each on a new timeline only where it can run in parallel, then simplify by platform guarantees. Draw before the code, redraw from zero after a change.
**Count the orderings and prune them; do not trace them all.** Two single-action timelines admit three orderings, two three-box timelines with one constrained start admit ten, and real systems generate thousands or millions. Tracing them all is impossible at realistic sizes, and that is the pivot: correctness comes from a structural guarantee that deletes orderings, never from green runs that may never see the interleaving a production week will.
**Only pairs touching the same resource need analysis.** Annotate every step with the resource it touches, then for each pair that shares one check all three relative orders: simultaneous, left first, right first. Decompose before you draw: an increment on a shared value is a read, a calculation, and a write, and one box hides the race the pair analysis exists to find. Explicit temporaries make it visible.
**Duration is never synchronisation:** the rare interleaving becomes common under load.
## 3. The ladder
Ranked: earlier rungs remove the problem, later rungs manage it.
1. **Fewer timelines,** often outside your control.
2. **Shorter timelines,** by converting actions to calculations and reading shared values once into explicit parameters.
3. **Fewer shared resources,** preferring a single worker, which cuts the orderings you must think about rather than the orderings.
4. **Coordinate the sharing that remains** with a primitive.
5. **Manipulate time as a first-class concept,** since a platform's implicit model of ordering and repetition rarely fits.
### Rung three: separate before you serialize
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.
**Pattern:**
1. **Identify shared mutable state** (files both read and write, branches both push to, APIs both define and consume).
2. **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.
3. **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.
## 4. The laws that survive translation
**Never block the scheduler, whatever it is called.** Blocking is holding the scheduler from switching tasks for a long period; I/O counts, and so does long-running compute. Two remedies and no third: run it off the scheduler's own workers, or break it up with yield points. Scheduler throughput is the shared resource nobody names.
**Share by communicating where the language offers it.** "Share memory by communicating; do not communicate by sharing memory" (the Go community, via Bodner). Legibility is the argument before safety: a guarded value never says which worker owns it, while a passed value shows its flow. Convert passing to guarding only once it has caused a real performance problem.
**Bound everything unbounded.** Every queue, fan-out, and wait carries a ceiling that is a number a person chose for a reason they can say. Where only the latest result matters it may discard stale entries, correct only where discarded work has no independent effect.
**Whoever starts a unit of concurrency decides at the launch site how it stops.** Above leak-hygiene sits the method claim: an unterminated timeline never closes, so no cut across it, the line splitting timelines into halves that cannot interleave, holds, and its orderings never leave the set.
## 5. Primitives, a vocabulary of shapes
A primitive lets timelines share a resource safely, and the mechanism is always the same one: it removes undesirable orderings from the set. **Linearize** lets one instance of a timeline run at a time, and is the name to teach: the queue is the implementation, the guarantee is the point. **The cut** runs across the ends of several timelines, splitting each into halves that cannot interleave.
A primitive is an action, deliberately. It holds mutable state, defended rather than hidden: any timeline may call it and get predictable behaviour from state closed where nothing outside reaches it. What is built from calculations is what it coordinates, rung two. **Use the primitive your language or platform ships,** since hand-built shapes teach the reasoning, not the library, and are safe only on the single-threaded platform they were written for.
## 6. Operations that run twice
Design operations so they converge to the correct state regardless of how many times they run or where they start from. Every state-mutating operation should answer: "What happens if this runs twice? What happens if the previous run crashed halfway?"
**The pattern:**
- Convergent startup: scan for existing state, clean stale artifacts, adopt live sessions
- Content-based cleanup: compare by content equivalence, not creation order
- Idempotent scheduling: failed work respawns cleanly, fresh input regenerated after each cycle
**The test:**
1. What happens if this runs twice in a row?
2. What happens if the previous run crashed at every possible point?
3. Does re-execution converge to the same end state?
If any answer is "it depends on what state was left behind," the operation needs a reconciliation step.
Where a caller retries a request against your service, the request carries an idempotency key, and [idempotency-key.md](idempotency-key.md) says how to honour it: derived from the intent, claimed atomically, its payload guarded, the intent recorded before the effect, and kept as long as the longest retry chain.
## Sources
Normand, _Grokking Simplicity_, is the sole witness behind sections 2 and 5 and the ladder of section 3, whose third rung also takes pstack's principle-separate-before-serializing-shared-state; section 6 is pstack's principle-make-operations-idempotent and addyosmani's api-and-interface-design. Other sources: Bodner, _Learning Go_ (3e early release, revisit April 2027); Latour, _Go Pocket Projects_; Matthews, _Code Like a Pro in Rust_. The maintainer's graded research records are provenance, not required installed support files. The complete method above is available here.
SKILL.md as installed, byte for byte SHA-256 97bdb1d950debba98c7d1d0fea8fadb90f665b03ff40416f25bbf0a2c356c482