| name | fabrico-planning-migration |
| description | Plan the migration of a legacy web app to a modern target — modern web (Next.js/React), native iOS (SwiftUI), or cross-platform mobile (React Native/Expo). Maps old behavior to a target stack, builds a feature-parity matrix, plans data and auth migration, adapts desktop UX to mobile where needed, and flags risks. Use after reverse-engineering a SPEC.md and before rebuilding with /fabrico-autopilot. |
Planning a legacy migration / modernization
Bridge a (reverse-engineered) SPEC.md to a concrete rebuild on a chosen target. The SPEC stays
platform-agnostic; this skill produces a MIGRATION-PLAN.md that pins the target, proves feature parity, and
surfaces what won't port 1:1 — so the autopilot build has a clear, de-risked path.
Inputs
- A
SPEC.md (ideally from fabrico-reverse-engineering-spec, with a Source-mapping appendix).
- The chosen target (or pick one with the framework below).
- Any constraints: offline support, App Store distribution, existing backend/API to keep, data export access.
Output
MIGRATION-PLAN.md containing: chosen target + rationale, stack mapping, feature-parity matrix, data-migration
plan, auth/session plan, UX-adaptation notes, risk register, and a phased rollout. This plan + the SPEC are what
/fabrico-autopilot (via the engineering manager) consumes.
Step 1 — Choose the target (if not given)
| Target | Best when | Default stack |
|---|
| Modern web | reach via browser, SEO, desktop+mobile web, fastest path | Next.js (App Router) + TS + Tailwind, Prisma + Postgres, Auth.js |
| Native iOS | iOS-only, deep platform integration (push, widgets, offline), App Store first | Swift + SwiftUI, async/await, Core Data/SwiftData, URLSession |
| React Native / Expo | iOS and Android from one codebase, team knows JS/TS | Expo + React Native + TypeScript, React Navigation, TanStack Query |
Trade-offs to weigh: audience/platforms, team skills, offline & device features, distribution (web vs App Store),
budget/time, and whether an existing backend/API is kept (web & RN reuse REST/GraphQL easily; native iOS too, but
UI is rebuilt). Record the decision and rationale.
Step 2 — Stack & pattern mapping
Map legacy patterns to target equivalents, e.g.: server-rendered multi-page → SPA/RSC or native navigation;
jQuery/Bootstrap widgets → component library; server sessions → token/session strategy of the target; synchronous
page reloads → async data fetching + optimistic UI. Produce a table: legacy concern → target approach.
Step 3 — Feature-parity matrix
From the SPEC's Source-mapping appendix, list every feature/story and mark: port as-is, adapt (changed for
the target — say how), or drop (with reason + user sign-off). This matrix is the contract for "did we reach
parity". No feature leaves the legacy app silently.
Step 4 — Data migration
Decide: greenfield schema rebuilt from the inferred model, or migrate existing data. If migrating, plan
export → transform → import, identity/relationship preservation, and a verification step (counts, spot checks).
If you lack access to the legacy database, note it as a blocker for the data step (the app can still be rebuilt
with seed/demo data).
Step 5 — Auth, sessions & integrations
Plan how users authenticate on the target, whether existing accounts/passwords migrate (often a reset flow is
simpler and safer), and how each integration from the SPEC is handled (keep same provider, swap, or stub behind an
interface until keys are provided — never block the whole build on one integration).
Step 6 — UX adaptation (esp. web → mobile)
Desktop-era patterns rarely port 1:1 to mobile. Note adaptations: dense tables → cards/lists with filters; hover
actions → tap/long-press/swipe; multi-column forms → steppers; mouse-only interactions → touch; deep menus →
tab/stack navigation. Keep behavior/intent from the SPEC; change the presentation to fit the target.
Step 7 — Risk register & phasing
List risks (data loss, integration gaps, parity misses, platform limits, scope creep) with mitigations. Choose a
rollout: big-bang rebuild for small apps, or strangler-fig / module-by-module for large ones (rebuild
high-value modules first, run old and new in parallel, cut over per module). Sequence the epics accordingly.
Guidance
- Preserve behavior, modernize presentation. Parity is about what users can do and the data, not pixels.
- De-risk integrations and data early — they cause the most surprises in migrations.
- Make the parity matrix the source of truth for "done", and feed the chosen target into the SPEC's
"Target" section before the build runs.
