Migration Assessment — act101 Agent Skill

Migration Assessment

Depth: Level 2 (Investigate).

See ../analysis-protocol/references/protocol.md for: artifact directory structure, the investigation loop, depth levels, summary format, token budget rules, and project map structure. Read that document before proceeding.

Phase 1: Parallel Tool Dispatch

Dispatch all available tools in a single parallel batch. Each subagent runs one tool, saves raw JSON to raw/<tool-name>.json, returns a structured summary.

Must-have tools:

If analyze_readiness is unavailable, report that and stop — no useful migration assessment is possible without it.

Extended tools (use if available, skip and note in manifest if not):

Phase 2: Investigation

For each file or module scored "hard" in readiness, or flagged as a hard blocker:

Platform dependency hypothesis example:

Hypothesis N: The <module> module is migration-ready despite <N> platform deps because they're isolated behind a <WrapperClass> abstraction. Evidence: analyze_readiness scored it "needs-work"; analyze_platform_deps shows N imports of <platform-api>. Confirming query: skeleton on the wrapper file + references on the platform import symbol. Confirms if: Only the wrapper file imports the platform module directly. Refutes if: Multiple files import the platform module directly.

Complexity blocker hypothesis example:

Hypothesis N: <file> is a hard blocker due to dynamic dispatch, not complexity. Evidence: analyze_readiness scored it "hard"; patterns flagged reflection/eval use. Confirming query: skeleton on the file to count dynamic call sites. Confirms if: Multiple reflection/eval call sites with no static alternative. Refutes if: Single call site that can be wrapped or replaced.

Save investigation notes to investigation/hypothesis-N.md.

Report Structure

# Migration Assessment: <project name>

## Readiness Summary
Ready / Needs work / Hard counts with percentages.
Overall verdict: **Ready** / **Needs work** / **Hard** — with confidence note.

## Recommended Migration Order
Foundation modules first (high fan-in, low fan-out — ported early, depended upon).
Orchestrators last (low fan-in, high fan-out — ported after their dependencies).
Numbered list with rationale per module.

## Porting Blockers
Per-file list with context from investigation.
Distinguish clearly:
- **Hard blockers:** eval, reflection, FFI, dynamic dispatch — no mechanical equivalent
- **Soft blockers:** high complexity, tight coupling — require refactor before porting

## Platform Dependencies
By category (filesystem, network, OS, process, browser, FFI).
For each dependency:
- Which files use it
- Wrapped vs. direct (direct = higher porting cost)
- Adaptation strategy for the target language

## Type Boundary Gaps
Modules with low type completeness.
Per-gap: module path, missing type annotations, impact on mechanical translation.

## Language Feature Concerns
Features with no direct equivalent in the target language.
Per-feature: count, affected files, suggested adaptation approach.

## Inheritance Complexity
Deep hierarchies and diamond inheritance patterns that complicate porting.
Per-finding: chain depth, members, recommended simplification before porting.

## Dependency Depth
Deepest dependency chains (leaf modules to port first).
Per-chain: length, root, leaf, recommended port order.

## Per-Module Readiness Cards
For each top-level module:
- Readiness score: ready / needs-work / hard
- Blocker count (hard / soft)
- Platform dep count
- Recommended action

Project Map Updates

Appends or updates the "Migration Readiness" section. Appends to the Analysis History table.

Optional Enrichment: Security & History Evidence

The readiness scores above are structural/heuristic. When the workspace has the relevant evidence, enrich the plan so the recommended migration order reflects real porting risk — code that is hard to port AND dangerous AND historically volatile — not just structural readiness. This is optional: skip any dimension whose evidence or tier is unavailable and mark it UNASSESSED (never a clean bill).

Tier: composed tools enforce their own tiers — unsafe_surface Free, secret_surface Engineer, taint_flow/coverage_overlay/ownership_map Architecture, churn_hotspots Free for a single file / Architecture in workspace mode. If a tool is tier-blocked, its dimension is UNASSESSED — say so.

Honesty caveat: taint_flow/secret_surface/unsafe_surface report modeled_kinds — read it per call. A non-empty mask means the dimension was modeled for that grammar (an empty finding is then genuine); an empty/absent mask means it was not modeled — "no evidence," not "clean." coverage_overlay/ churn_hotspots/ownership_map reflect one coverage run and the git history present; state the window and unmapped.

Enrichment workflow (after the structural plan):

1. Run unsafe_surface and secret_surface per module; run taint_flow on entry functions. Any unsafe construct, secret surface, or live taint path raises that module's effective difficulty above its structural score.
2. coverage_overlay (lcov report) — a low-coverage module cannot be safely verified after porting; front-load test work or reorder.
3. churn_hotspots (workspace) and ownership_map — a high-churn or low-bus-factor module is a scheduling risk: stabilize or pair-port it.
4. Recompute the order: structurally-ready AND well-tested AND low-risk first; hard + dangerous + volatile last (or split first). Reclassify any soft blocker that an unsafe/taint/secret finding promotes to a hard blocker.

When enrichment runs, each readiness card adds: taint paths, secret/unsafe hits, coverage %, churn rank, and bus factor — and each blocker cites which evidence dimension fired.

Monorepos: frame readiness cards by package, not directory

When the repo is a workspace with package manifests, run the structural pass at package granularity so readiness cards map to the team's real packages (workspace members), not arbitrary directories:

• analyze_clusters and analyze_layers with granularity: package cluster and layer the package dependency graph (DependsOn edges parsed from manifests), giving the true cross-package porting order — port a package only after the packages it depends on.
• analyze_conformance with granularity: package evaluates deny rules against package names, so a "don't let package X depend on Y" boundary is checked at the level the team actually reasons about.

Which manifest kinds were modeled is reported from the graph's package nodes (empty when none) — never assume an ecosystem is covered; read what was modeled. Fall back to file/directory granularity when no workspace manifest is present.