state-ground-truth — Claude Code rule: keep state, not visuals
state-ground-truth — a rule that stops agents from storing derived visual values in state. Keeps React and Reanimated logic centered on facts.
MIT ★ 1,216 updated 2026-10-24
/plugin marketplace add fcakyon/claude-codex-settings
/plugin install react-skills@claude-settingsWhat state-ground-truth does
The state-ground-truth rule pushes agents to store only actual facts in useState and Reanimated shared values: pressed, progress, isOpen. Visual outputs such as scale, opacity, and translateY get computed from that state through interpolation or a plain expression.
The rule's example: instead of setting scale = 0.95 on tap, store pressed = 1 and derive scale with interpolate(pressed.get(), [0, 1], [1, 0.95]). In plain React the same idea applies: height = isExpanded ? 200 : 0 beats keeping height in its own useState and syncing it in useEffect.
Why bother: one source of truth makes debugging easier, since pressed = 1 reads clearer than scale = 0.95. Adding opacity or rotation later just means another interpolation from the same value. Install via the marketplace: /plugin marketplace add fcakyon/claude-codex-settings, then /plugin install react-skills@claude-settings, which writes .claude/rules/state-ground-truth.md.
What it helps with
- Separate real state from derived visual values
- Remove
useEffectblocks that sync derived numbers - Add new animations without duplicating state
- Read state values during debugging without mental math
Example prompts for the agent
- Check this component: state should hold facts, not visual values
- Rewrite the tap animation to store
pressedinstead ofscale - Find
useStatecalls holding derived values and simplify them
How to install state-ground-truth
1Plugin marketplace
/plugin marketplace add fcakyon/claude-codex-settings/plugin install react-skills@claude-settings2Manually: put the files in place
.claude/rules/state-ground-truth.mdThe paths frontmatter field limits the files
AGENTS.md
Codex reads AGENTS.md: paste the rule text there
Manually: put the files in place
.cursor/rules/state-ground-truth.mdcFrontmatter: description, globs, alwaysApply
Manually: put the files in place
.github/instructions/state-ground-truth.instructions.mdThe applyTo field sets which files it applies to
Manually: put the files in place
.devin/rules/state-ground-truth.mdManually: put the files in place
.clinerules/state-ground-truth.mdStep by step, with commands for each platform: AGENTS.md vs CLAUDE.md: what they are and which one to use
Questions about state-ground-truth
How do I install state-ground-truth in Claude Code?
Run /plugin marketplace add fcakyon/claude-codex-settings, then /plugin install react-skills@claude-settings. The rule lands in .claude/rules/state-ground-truth.md.
What does the state-ground-truth rule do?
It requires useState and Reanimated shared values to store only real state such as pressed, progress, or isOpen. Visual values like scale or opacity should be computed from that state.
Does the rule apply without Reanimated?
Yes. It includes a plain React example: derive height directly from isExpanded instead of keeping it in a separate useState and updating it in useEffect.
Source text
state-ground-truth.md · MIT
---
title: State Must Represent Ground Truth
impact: HIGH
impactDescription: cleaner logic, easier debugging, single source of truth
tags: state, derived-state, reanimated, hooks
---
## State Must Represent Ground Truth
State variables—both React `useState` and Reanimated shared values—should
represent the actual state of something (e.g., `pressed`, `progress`, `isOpen`),
not derived visual values (e.g., `scale`, `opacity`, `translateY`). Derive
visual values from state using computation or interpolation.
**Incorrect (storing the visual output):**
```tsx
const scale = useSharedValue(1)
const tap = Gesture.Tap()
.onBegin(() => {
scale.set(withTiming(0.95))
})
.onFinalize(() => {
scale.set(withTiming(1))
})
const animatedStyle = useAnimatedStyle(() => ({
transform: [{ scale: scale.get() }],
}))
```
**Correct (storing the state, deriving the visual):**
```tsx
const pressed = useSharedValue(0) // 0 = not pressed, 1 = pressed
const tap = Gesture.Tap()
.onBegin(() => {
pressed.set(withTiming(1))
})
.onFinalize(() => {
pressed.set(withTiming(0))
})
const animatedStyle = useAnimatedStyle(() => ({
transform: [{ scale: interpolate(pressed.get(), [0, 1], [1, 0.95]) }],
}))
```
**Why this matters:**
State variables should represent real "state", not necessarily a desired end
result.
1. **Single source of truth** — The state (`pressed`) describes what's
happening; visuals are derived
2. **Easier to extend** — Adding opacity, rotation, or other effects just
requires more interpolations from the same state
3. **Debugging** — Inspecting `pressed = 1` is clearer than `scale = 0.95`
4. **Reusable logic** — The same `pressed` value can drive multiple visual
properties
**Same principle for React state:**
```tsx
// Incorrect: storing derived values
const [isExpanded, setIsExpanded] = useState(false)
const [height, setHeight] = useState(0)
useEffect(() => {
setHeight(isExpanded ? 200 : 0)
}, [isExpanded])
// Correct: derive from state
const [isExpanded, setIsExpanded] = useState(false)
const height = isExpanded ? 200 : 0
```
State is the minimal truth. Everything else is derived.
© fcakyon · MIT · fcakyon/claude-codex-settings