agentleFS
naomiaronaomiaro/waveform-playlist/.claude/skills/state-ownership/SKILL.md

state-ownership

Skill1.7k starsChanged yesterdayMITView on GitHub

Use when designing, planning or reviewing a change in packages/ that adds, moves or shares state - a prop paired with a change callback, a provider or context value, a store or cache, engine or adapter state mirrored in React, undo history, a value two components or two packages both read or change - and when a bug looks like state reverting, a lost update, a value that is stale after loading, or two parts of the system disagreeing.

Trending

Quiet this year.thin dataabout the whole repository

Dec 2025: 0 mentionsJan 2026: 0 mentionsFeb 2026: 0 mentionsMar 2026: 0 mentionsApr 2026: 0 mentionsMay 2026: 0 mentionsJun 2026: 0 mentionsJul 2026: 0 mentionsAug 2026: 0 mentionsSep 2026: 0 mentionsOct 2026: 0 mentionsNov 2026: 0 mentions
Dec 2025Jun 2026Nov 2026
Mentions a month of the naomiaro/waveform-playlist repository that our weekly crawl found: only 11 in all, so this is a hint, not a trend. There is no adoption data for this file yet.

Who's talking about naomiaro/waveform-playlist

The biggest 5 of 11 mentions linking to the repository that our crawl found. Each line is their own headline.

See all 11

Talked about on GitHub, Stack Overflow and Hacker News (11 times).

On GitHub · 8

3 more on GitHub

On Stack Overflow · 2

On Hacker News · 1

The file

We split this skill into the rules it gives an agent

5 rules. About 0 are common, 5 are distinctive, and 0 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈5

    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
  1. Distinctive:

    Before any design text, write this table for every piece of state the change reads or writes.

    line 16
  2. Distinctive:

    Not a second place: a value computed from the owner during render, a cached projection that is never written back, a one-way cache …

    line 35
  3. Distinctive:

    When a row has more than one entry under "Stored where", the next message to the maintainer is about that row and has these five parts, in …

    line 41
  4. Distinctive:

    Look for a write whose value was computed earlier than it lands.

    line 66
  5. Distinctive:

    Ask the reviewer one question before any other: "which state here is still stored in two places, and which place writes back?"

    line 79

≈ “Common” is an estimate: at least 1 in 5 of the 372,429 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.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

State ownership

Every piece of state has one owner. Everything else subscribes to it and changes it by asking the owner. (Maintainer, 2026-11-13.)

Scope: every package. It applies to a design before code, to a review, and to a bug hunt.

First: the owner table

Before any design text, write this table for every piece of state the change reads or writes. It is the first thing in the design message, the plan and the review.

StateStored where (EVERY place)Who writes each placeOwnerHow others change it

Fill "Stored where" from the code, not from the feature's description: every useState, ref, field, Map and array that holds the value or a copy of it, in React, in the engine, in an adapter and in the app. Count these as places:

  • The app's state behind a controlled prop. <X value={v} onChange={setV}> stores the value in the app. If the library also keeps and changes it, that is two places.
  • A "working copy" that is reset from a prop, or overwritten from an event.
  • A ref or a state that mirrors another object's state.
  • A snapshot (undo history, a drag's saved start) that captures values some other object owns.

Not a second place: a value computed from the owner during render, a cached projection that is never written back, a one-way cache downstream (what an audio adapter holds).

A row with two places

When a row has more than one entry under "Stored where", the next message to the maintainer is about that row and has these five parts, in this order, and nothing after the fifth:

  1. The owner table.
  2. The row with two places, in a sentence: what is stored twice, and who writes each.
  3. One sequence in which the two places disagree (next section).
  4. The options, each named, with what it costs: make one place the owner and have the other subscribe (say which, for each candidate), or keep both for now and say which side wins in each order.
  5. The recommendation, and the question.

The feature's own design, its API and its tests are the following message, written for the option the maintainer chose.

This holds when the two places are older than the change. A feature that adds a field to state with two owners gives the field two owners.

The order of events

For every row that is written from more than one place, or across a callback, a promise or an effect, write the sequence both ways round: A writes then B, B writes then A. For each step say what value each place holds.

Look for a write whose value was computed earlier than it lands. A callback that hands back a whole array or object is one: the array was built from an older state, and storing it overwrites whatever was written in between. A functional update does not help when the payload itself is the old whole value.

In React the order within one commit is: render, layout effects, passive cleanups, passive effects; then async continuations and store notifications.

After choosing an owner

  • Moving a seam is not removing it. List every other object that still stores the value. If one of them writes back to the owner, there are still two owners.
  • Ask the reviewer one question before any other: "which state here is still stored in two places, and which place writes back?"
  • State a consumer can see changes hands: list what each consumer tree does before and after (the skill design-proposals, "Nothing breaks is a claim about behaviour").

Run it where both sides are real

A sequence that crosses React and the engine is run in a browser before it is called correct. Unit tests with a fake adapter passed while a real page lost rows. The probes are in the skill browser-probes, the dev-server rules in root CLAUDE.md and the skill e2e-playwright.

Shapes that hold one owner

NeedShapeIn this codebase
Many readers, few of which care about each changeAn owner object with subscribe / getSnapshot, read with useSyncExternalStore and a selector that returns a primitive or a cached object; changed through its methodsValueSource (packages/core/src/valueSource.ts), EffectsRack (packages/browser/src/effects/effectsRack.ts)
Feedback during a gesture, one committed change at the endA view-only preview that only the affected component follows; the owner is written once, on release; cancel clears the previewannotationPreview (packages/browser/src/providerInternals/useAnnotationState.ts), the trim preview (providerInternals/useTrimPreview.ts)
Data the app, the view and the audio engine all changeAn owner object the app creates and hands to the provider; the provider derives what it publishes during render and writes nothing back; every change is a method call on the ownerThe Arrangement (packages/engine/src/arrangement/), made with useCreateArrangement, read through useArrangementView (packages/browser/src/providerInternals/)
State that must survive a remountThe owner lives outside the component; no effect cleanup clears itEffectsRack; the skill react-patterns, "A store owned by a hook"
An option several components draw withOne small context, read where it is used; no prop beside itWaveformViewOptions

Common mistakes

  • Calling the app's state "the single source" while the engine keeps and edits a copy.
  • Fixing one disagreement between two owners with a guard, a merge or a flag. Each closes one sequence; the next sequence needs another.
  • Putting a new field on an object without asking who owns the object.
  • Writing every pointer move of a drag into the owner.
  • Declaring a value derived when something writes it back.

Download now (ZIP)

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
What did you use it for? e.g. Reviewing pull requests in a Rails app

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.