State-driven UI

Scope

Use this skill to design and implement UI behavior as a pure projection of state. Model behavior with reducer + events. Isolate side effects in React Query mutation callbacks. Keep components render-only and intent-only.

Use this skill when

• The feature has phases (idle, editing, saving, confirming, error).
• The feature has async behavior (save, validate, retry, generate).
• The feature has cross-component or cross-route behavior.
• The current design relies on boolean soup or lifecycle timing.
• Correctness must survive re-rendering and concurrency.

Do not use this skill when

• The change is purely presentational.
• The behavior is trivial and isolated to local UI state.
• There is no workflow and no side effects.

Required approach

Follow this order. Do not skip steps. Do not write component code before steps 1 to 4 are complete.

1. Define the state model and ownership boundaries.
2. Define events (user intent and system outcomes).
3. Define transitions as a pure reducer (event -> next state).
4. Define side effects and bind them to events.
   • Use React Query mutation callbacks to emit outcome events.
5. Define selectors (derived values).
6. Implement components as projection + intent emission only.

Output expectations

When using this skill, output in this structure:

1. State model
2. Events
3. Transition map (reducer rules)
4. Side effects plan (React Query mutations and callbacks)
5. Selectors
6. Component boundaries
7. Implementation steps
8. Design rationale (why, what, why not, skipped, trade-offs)

Canonical documents

• Full compiled guidance for agents: AGENTS.md
• Source rules (modular): rules/
• Patterns and examples: references/

Rule catalog

Read the relevant rule files from rules/ as needed. Treat AGENTS.md as canonical when uncertain.

Construction and modeling

• rules/flow-ui-projection.md
• rules/flow-intents-only.md
• rules/reducer-events-drive-state.md
• rules/reducer-single-phase.md
• rules/fsm-no-boolean-soup.md

Effects and async (React Query)

• rules/effects-no-effects-in-components.md
• rules/query-mutation-callbacks.md
• rules/query-stale-response-guard.md

Cross-cutting behavior

• rules/routing-explicit-decision-state.md
• rules/url-validated-boundary.md

Correctness and maintainability

• rules/derive-derived-state-as-selectors.md
• rules/identity-stable-ids-and-keys.md
• rules/determinism-no-lifecycle-dependence.md

Documentation and reasoning

• rules/docs-rationale-at-boundaries.md