wellspring

wellspring

!checklist init ${CLAUDE_SKILL_DIR} --force

A wellspring is the source a stream flows from — and the whole art here is to keep that source single, and let everything downstream be derived from it rather than stored again. wellspring is the third skill of the surface suite, the lens over state architecture — the heart of the system, the place the suite's deep models (state, the two graphs) finally become the judgment you make at every keystroke, and the place that sets the ceiling on the project's complexity. Its product is a written state-classification map: every meaningful piece of state assigned to the bucket that owns it, the source of truth minimized, the hard interactions drawn as explicit machines, and the data-flow conventions fixed. It runs across gated stages and will not advance past a GATE until the checklist tool clears it — order enforced, substance yours.

The governing fact: nearly all frontend complexity is state having more than one copy. The "same truth" lives at once in the DOM, the in-memory model, the server database, the URL, localStorage, a component's local state — and the overwhelming majority of bugs are not wrong logic but these copies drifting out of sync (the server updated but the view didn't; the URL changed but the view didn't; two components each kept a copy and they disagree). So the craft is subtraction: classify each piece of state into the single bucket that owns it, keep the source of truth minimal, and derive everything else. Do that and a surprising thing happens — most of what felt like "global state" turns out to be server-cache in disguise, and once you split it out the global store shrinks to a fraction of its size. Much of the pain people blame on Redux is really server-cache mismanaged as local state.

This is where the agent era bites:

• The agent stores derived state, signing a sync contract it will break. Asked for a filtered list, it keeps the list, the query, and the filtered result — then wires a useEffect to sync them. Every stored derivative is a "remember to update this everywhere" contract, and the next session forgets. Derived values are recomputed, never stored.
• The agent dumps everything into one global store. It does not feel the cost of a bloated store or a piece of state living in the wrong bucket, so server-cache, URL state, and local UI state all get jammed together with one lifecycle. The store's size is the thermometer: a big global store is near-proof the classification is wrong.
• The agent writes a pile of boolean flags instead of a state machine. isLoading, isError, isSubmitted as independent booleans — so the machine is implicit, and the illegal combinations (loading and error and success) it permits are exactly the 3 a.m. bugs. It also prop-drills rather than seeing the two-graph mismatch, and over-abstracts components into config-driven monsters with no escape hatch.

Read references/the-membrane.md first — the heart; for wellspring, lean on two axes: state (the source-of-truth discipline, server-state-is-a-cache, illegal-states-unrepresentable) and the two graphs (the component tree is shaped for visual nesting; the data-dependency graph is an arbitrary DAG; every state tool is a bypass for where they disagree). Load at the start, re-check at every gate.

Speak the user's language. The classification calls are the user's — is this derived or independent, is this server-cache or genuinely client-owned, does this belong in the URL. Read their fluency and gloss a term on first use (source of truth, derived state, server-cache vs client state, URL state, a state machine / statechart, prop drilling, composition, signals/atoms, the rule of three). A bucket assignment the user can't follow is an architecture imposed, not shared.