Skip to main content
rule CX Codex

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

Install into Claude Code · Plugin marketplace All methods and platforms ↓
/plugin marketplace add fcakyon/claude-codex-settings
/plugin install react-skills@claude-settings
Open on GitHub

What 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 useEffect blocks 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 pressed instead of scale
  • Find useState calls 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-settings

2Manually: put the files in place

.claude/rules/state-ground-truth.md

The paths frontmatter field limits the files

Step 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

Similar IDE rules

All IDE rules for Agent setup: memory, context, orchestration →

From the same set113

The whole set →
setup setup guides the agent through installing and debugging Paper Search CLI. Replaces Docker MCP with direct CLI calls for paper search and DOI lookup. CX Codex +1 ★ 1,216repo stars review-pr The review-pr skill checks pull requests for bugs, regressions, risky changes, and missing tests. Use it to get a focused list of issues before approving a PR. CX Codex +1 ★ 1,216repo stars animation-gpu-properties animation-gpu-properties — a rule that keeps animations off width, height, top, left, margin and padding and moves them onto transform and opacity, so no layout pass runs per frame. CX Codex +1 ★ 1,216repo stars rerender-no-inline-components The rerender-no-inline-components rule flags React components declared inside other components, a pattern that causes remounts on parent renders. Use it when state, focus, or scroll position keeps resetting. CX Codex +1 ★ 1,216repo stars ui-styling ui-styling enforces modern React Native styling practices: smooth continuous borders, gap spacing, CSS boxShadow syntax, and native gradients. CX Codex +1 ★ 1,216repo stars ui-measure-views ui-measure-views guides agents to measure React Native view dimensions using useLayoutEffect alongside onLayout without triggering unneeded re-renders. CX Codex +1 ★ 1,216repo stars create-issue create-issue is a Claude Code skill for drafting or revising issues about bugs and missing features. It can also refine an issue title or body before publication. CX Codex +1 ★ 1,216repo stars list-performance-item-memo list-performance-item-memo — a rule for React list rows: split the item into primitive props so memo() can compare them shallowly and skip a render when nothing changed. CX Codex +1 ★ 1,216repo stars

Project sponsors

Companies that keep this analytics open