Best Practices

The best practices skill contains 46 rules sourced from vercel-labs/agent-skills (MIT License) plus rules discovered through plugin testing. Each rule has full incorrect/correct code examples in reference files.

When loaded

Activated during Phase 4 (Architecture) to constrain design decisions and during Phase 6 (Review) Pass 4 for code quality checks. Also loaded when reviewing React Native code, optimizing list performance, implementing animations, or auditing UI components.

CRITICAL Rules (runtime crashes)

These are checked regardless of review scope.

RN-1.1: Never use && with potentially falsy values

{count && <Badge />} renders “0” as text when count is 0, crashing React Native.

Use {count > 0 && <Badge />} or {count ? <Badge /> : null} instead.

RN-1.2: Wrap all strings in <Text>

A string as a direct child of <View> causes a runtime crash. Always wrap in <Text>.

RN-16.1: Don’t define components inside components

Creates a new type every render, causing React to remount (destroying state, views, animations). Symptoms: TextInput loses focus, animations restart, scroll resets.

RN-16.3: Use Promise.all() for independent async operations

Sequential await on independent calls wastes 2-10x time.

Rule Index by Category

Priority	Category	IDs	Key Patterns
1	Core Rendering	1.1, 1.2	&& conditionals, bare strings in Views
2	List Performance	2.1-2.8	FlatList, renderItem, inline objects, virtualization
3	Animation	3.1-3.3	Reanimated, transform/opacity only, GestureDetector
4	Scroll	4.1	Never store scroll position in useState
5	Navigation	5.1	Only native navigators (native-stack, native tabs)
6	React State	6.1-6.3	Minimize state, derive values, dispatch updaters
7	State Architecture	7.1	State = ground truth, visuals = derived
8	React Compiler	8.1-8.2	Destructure functions early, .get()/.set() for shared values
9	UI	9.1-9.9	expo-image, Pressable, native modals, native menus, onLayout
10	Design System	10.1	Compound components over polymorphic children
11	Monorepo	11.1-11.2	Native deps in app dir, single dep versions
12	Third-Party	12.1	Import from design system folder
13	JavaScript	13.1	Hoist Intl formatter creation
14	Fonts	14.1	Load fonts natively at build time
15	Queries/Animations	15.1-15.3	Reactive query hooks, no Reanimated layout anims in lists, theme hooks inside items
16	Re-renders/Async	16.1-16.7	No inline components, lazy state init, Promise.all, Set/Map lookups

HIGH Impact Rules (summarized)

Rule	Constraint
2.1-2.8	All scrollable data uses FlashList/LegendList. List items receive primitives, not objects. Callbacks hoisted to root. No queries or heavy hooks inside items. Compressed images. Item types for heterogeneous lists.
3.1	Only animate transform and opacity (GPU-accelerated). Never animate width, height, margin, padding.
4.1	Never store scroll position in useState. Use Reanimated shared values or refs.
5.1	Only native navigators: native-stack, native bottom tabs. No JS-based stack/tab navigators.
9.5	Use expo-image for all images (not Image from react-native).
9.7	Use native menus (zeego) for dropdowns instead of JS pickers.
9.8	Use native modals over JS bottom sheets.
15.1	Use reactive query hooks, not imperative queryClient.getQueryData cache reads.

Usage in the Pipeline

During Architecture (Phase 4)

The architect reads CRITICAL and HIGH rules relevant to the feature and applies constraints to the blueprint.

During Review (Phase 6, Pass 4)

1. Always check CRITICAL rules 1.1, 1.2, 16.1
2. Scan code for patterns matching HIGH/MEDIUM/LOW categories
3. Read the full reference file for each matched rule
4. Report findings with citation: [RN-2.1] Rule Name -- IMPACT (confidence N)