migration-advisor

name

migration-advisor

description

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".

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.