# Migration Advisor > Front door for legacy migrations — assess a legacy system from shallow read-only signals (repo probe, git history, a reachable running instance) plus a short interview, then recommend an entry path (rehost, replatform, rearchitect) and an ordered sequence of migration skills to invoke. Produces migration/PLAN.md with its evidence shown; routes, never executes. Use when someone wants to migrate, modernize, or port a legacy enterprise Java or web application and needs to know where to start. Triggers on "migrate this legacy app", "how do I modernize this", "port this old system", "where do I start with this legacy codebase", "plan a migration". - Skill: `adambien/migration-advisor` (Agent Skill, multi-file: 2 files) - Install (CLI): `npx skillmds@latest add adambien/migration-advisor` - Raw SKILL.md: https://api.skillmd.com/api/skills/adambien/migration-advisor/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Coding & Dev Tools - Author: AdamBien (https://skillmd.com/u/adambien) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/adambien/migration-advisor --- # Migration Advisor The triage front door. Legacy migration is judgment-heavy and the entry-path choice is a human decision — this skill gathers the cheap signals that inform that choice, recommends a path and a sequence, and hands off. It **routes, never executes**: every step it recommends is invoked explicitly by a human, and each produces a reviewable artifact. Stay shallow. The value is finishing in under a minute on a repo you have never seen. Deep vocabulary mining is `/concept-extractor`; behavior capture is `/characterization-tests`. Those are steps *in* the plan, not prerequisites to producing it. ## Data Sources Use whatever is present; state in the plan which were available — a plan built without git or a runnable instance is more heuristic, and must say so. ### Repo probe (always) Read-only counts and pattern hits, never comprehension: - **Platform / age** — build files: `javax.*` vs `jakarta.*`, servlet/EJB/JSF/Spring versions, target JDK; or `package.json` with jQuery/AngularJS/Backbone. - **Size / shape** — module, package, and file counts; LOC order of magnitude; density of `*Manager`/`*Impl`/`*Util`/`*Facade` names (overengineering signal → concept pipeline pays off; small and clean → rearchitect directly). - **External dependencies** — count and identity of libraries with Java SE or platform equivalents (the replatform/simplifier signal). - **Test coverage** — presence and size of a test source tree (near-zero → characterization must come first; "1:1 lift" is risky). - **Surfaces** — JAX-RS resources, `web.xml` mappings, queue config, batch jobs; whether a runnable artifact exists (is characterization feasible, on which surface). ### Git history (if `.git` present) Aggregate `git log` / `shortlog` / `--numstat`, not per-file blame: - **Liveness** — last commit date, commit frequency: frozen (experts likely gone → lean on recorded behavior and async questionnaires) vs. active (strangle alongside ongoing work). - **Bus factor** — `git shortlog -sne`: contributor count and whether the top authors are recent. Pre-fills the interview's expert-availability question with names. - **Hotspots** — churn per file/package: where behavior is volatile and characterization should concentrate. - **Temporal coupling** — files that change together: empirical evidence that latent structure exists and the carve path will pay off. Note it; do not carve — that is `/bc-carver`. - **Code age** — old untouched code is safe to lift; recently churned code is where lift risk concentrates. Distrust the signal when history is shallow-cloned, squashed/rebased, dominated by reformatting or dependency-bump commits, or broken by large file moves. Say so rather than presenting distorted churn as fact. ### Running instance (if reachable) Confirm a surface responds; note base URL and health. Do not exercise it — that is characterization's job. ## Interview The routing-critical facts live in people's heads. Ask 3–4 enumerable questions with `AskUserQuestion`, **pre-filled from the probes** so the human confirms or corrects rather than starts blank: - Must the system keep running during migration? → rehost/replatform first vs. rearchitect directly. - Is a domain expert available? (offer the git bus-factor names) → concept path viability; live vs. async clarification. - Goal: clean modern runtime, or full BCE? → replatform-terminal vs. carve to sbce. - Platform EOL / compliance deadline? → urgency; favors lift-first. ## Output Write `migration/PLAN.md`: - **Findings** — the gathered signals, each with its source and the caveats that apply. Spot-checkable, never trust-based. - **Recommended path** — rehost, replatform, or rearchitect — with the *reasoning* (which signals drove it), so a human who knows the system can override a bad inference. - **Sequence** — the ordered skills to invoke (`/characterization-tests record` → … ), with steps marked skippable and why, and the decision points that need a human call flagged. - **Reference, don't restate** — link each step to its own skill README for detail; keep the plan thin so it does not drift from the skills. The plan is a recommendation with its evidence shown, not a verdict — candidates-not-verdicts applied to the routing decision itself. The human edits it before step one. ## Entry Paths - **Rehost** — 1:1 lift onto the target runtime, nothing else. Keeps running through a long migration or under EOL pressure. - **Replatform** — lift, then `/simplifier` passes under the characterization green bar. A valid terminal state, or preparation for the concept pipeline. - **Rearchitect** — recover vocabulary (`/concept-extractor` → `/concept-clarifier`), carve (`/bc-carver`), converge to specs (`/sbce` + stack skill). For overengineered systems where the structure hides the domain.