---
name: migration-research
description: Generate the migration RESEARCH document docs/migration/NNN-research-<component>.md for moving any legacy component (WCF service, ASP.NET MVC/WebForms front-end, Web API, Windows service, library, etc.) to a modern target (e.g. .NET 10 / ASP.NET Core). Produces an evidence-based analysis of the current component, its dependencies and native-library replacements, the 1:1 behaviour mapping, risks, and scope. Step 1 of the 3-document migration pipeline (research → tests → plan). Invoke explicitly only.
disable-model-invocation: true
---

# migration-research

Step 1 of the migration documentation pipeline. It produces **one file**:
`docs/migration/NNN-research-<component>.md`, the factual basis the test plan
(`migration-tests`) and implementation plan (`migration-plan`) build on.

`<component>` is whatever is being migrated — a back-end service, an ASP.NET
MVC/WebForms front-end, a Web API, a Windows service, a shared library, etc. The
structure below is the same regardless; adapt the wording to the component type
(operations/routes/pages/features) rather than assuming a service.

Canonical worked example to match in tone, depth and section structure:
**`docs/migration/001-research-ZPS.NServiceBusProxy.md`** (a WCF service — one
instance of the general pattern). Read it first.

## Core rules

- **Evidence-based, no assumptions.** Every element and claim must be grounded
  in code/config (cite `file:line`). What you cannot determine from the code goes
  in an explicit *Not determinable from code* note — never guess.
- **Confirm shape-changing decisions with the user.** Anything that materially
  changes the migration (target framework, auth, transport/library upgrades,
  scope, identity handling) is decided via `AskUserQuestion` and recorded under
  *Decisions (confirmed with user)* — do not silently pick.
- **1:1 first.** Default to faithful behaviour parity with the legacy service;
  call out deliberate deviations explicitly.
- **Prefer native Microsoft / built-in .NET libraries.** A central goal is
  deleting custom/third-party wrappers in favour of in-box replacements — make
  the remove/replace/keep call explicit per dependency.

## Procedure

1. **Pick the target component** from the user's request. Determine the next
   sequence number `NNN` = (highest existing `docs/migration/NNN-*` + 1), zero-padded
   to 3 digits. The first migration is `001`.
2. **Gather evidence** about the component — read its project file, source, configs,
   hosting/entry point (`.svc`, `Global.asax`, controllers, views, `Program`/`Main`),
   callers and downstream dependencies. For broad sweeps use `Explore` subagents so the
   main context stays clean; demand `file:line` citations back.
3. **Resolve open decisions** with `AskUserQuestion` before writing conclusions.
4. **Write** `docs/migration/NNN-research-<service>.md` using the format below.

## Required format

Mirror `001-research-*`. Sections:

1. **Title** — `# NNN – Research: <service> (<from> → <to>)`.
2. **Context** — what the service is, its single responsibility, why migrate,
   intended outcome.
3. **Decisions (confirmed with user)** — numbered list of the answers that fix the
   migration shape.
4. **Behaviour mapping (1:1)** — table: legacy unit (operation / route / page /
   feature) → new equivalent → downstream effect. Note exact field types and nullability
   where data is involved.
5. **Target architecture** — minimal target design + a *What disappears* list.
6. **Code removal → native Microsoft / .NET libraries** — table:
   `Current dependency | Used for (file:line) | Native replacement | Remove/Replace/Keep`.
7. **Risk(s)** — especially wire/contract/serialization compatibility with systems
   that stay on the old stack; include a fallback.
8. **Boundary (out of scope)** — what this task deliberately does not touch
   (e.g. callers that keep the old client until separately migrated).
9. **Reference files** — the legacy files to mirror and the new files to create.
10. **Verification** — how the migration is checked end-to-end later.

Keep it scannable: tables over prose, cite sources, no speculative content (YAGNI).