Template: Refactor shared code

Status: Reference

Task

Edit shared code in packages/ui/, packages/app/, or root configs. Examples: change a Tamagui token, modify MotionPressable, refactor a query hook factory, edit eslint.config.mjs.

Pre-implementation checks (MANDATORY)

Shared code has the largest blast radius. Skipping these checks is how regressions reach production.

1. Grep ALL consumers

# For a UI primitive (e.g. Card, Button, MotionPressable):
grep -rn "<PrimitiveName>" packages/features /home/sungkyu08/Dev/twomore-v2/apps --include="*.tsx" --include="*.ts" 2>/dev/null

# For a hook factory (e.g. createMutationHook):
grep -rn "<factoryName>" packages/app/src/presentation/hooks/ /home/sungkyu08/Dev/twomore-v2/apps --include="*.tsx" --include="*.ts" 2>/dev/null

# For a token (e.g. $primary, $borderSubtle):
grep -rn '\$<tokenName>' packages /home/sungkyu08/Dev/twomore-v2/apps --include="*.tsx" --include="*.ts" 2>/dev/null

Report: number of consumers + their file paths.

2. Read the most-complex consumer in full

Pick the consumer with the most usages of the symbol; read its full file. Confirm your change won't break its assumptions.

3. Confirm the change is necessary

• Does extending the existing API solve it? Prefer extension over modification.
• Does adding a new variant work? Prefer additive over breaking.
• If breaking: is there a migration path?

4. Plan the rollout

• Single commit, or multiple (one for the shared change, one per consumer)?
• Are there compatibility shims needed?
• What's the rollback path?

Files in scope

Depend on the specific change. Common shared files:

• packages/ui/src/<primitive>.tsx
• packages/app/src/presentation/hooks/<hook-factory>.ts
• packages/app/src/presentation/cache/index.ts
• apps/mobile/tamagui.config.ts
• eslint.config.mjs (Phase 14-prep onward)

Files OUT of scope

• Anything that doesn't directly need to change to satisfy the user's request. Do not refactor surrounding code "while you're there."

Implementation pattern

1. Make the smallest change that satisfies the requirement.
2. Run typecheck immediately after — fix any consumer breaks before continuing.
3. Update consumers if any need migration.
4. Update tests if behavior changed observably.
5. Run full validation suite.

Hard constraints

• AOR-1: blast-radius grep is mandatory before editing shared code (GREP-BEFORE-WRITE)
• AOR-2: match scope to what was requested; don't refactor while you're there (SCOPE)
• ARCH-1 through ARCH-7: do not violate the dependency rules even when "it would simplify the change"

Post-implementation verification

git status
git diff --stat                                         # confirm scope is reasonable

yarn typecheck                                          # exit 0
yarn run check                                          # tests pass

yarn workspace @twomore/web build                       # if change touches UI or platform-shared code
yarn workspace @twomore/mobile preflight

# Architecture contracts
yarn workspace @twomore/app jest --runInBand src/config/__tests__/architecture-archunit.test.ts

# If applicable: re-run consumer-specific tests
yarn workspace @twomore/<feature> jest

What to report

• Symbol modified + consumer count (from grep)
• Whether the change is additive, modifying, or breaking
• Whether all consumers were migrated in this commit, or follow-up needed
• Full validation results
• Honest assessment of risk: low / medium / high — and why