Skip to content

PATTERN Cited by 1 source

AI migration skill workflow

Pattern

Package a mechanical-refactoring migration workflow as a structured, multi-step AI skill with engineer verification checkpoints at risk boundaries. The skill is the artefact the AI executes; engineers sign off at defined checkpoints; progressive disclosure of context keeps the AI's context window focused on the current step.

Forces

  • Mechanical migrations scale poorly with manual labor — hundreds of feature-level conversions are tedious, error-prone, and previously deprioritized (see concepts/ai-assisted-refactoring-economics).
  • AI coding assistants excel at repetitive mechanical refactoring but drift without explicit structure.
  • Mistakes are costly in stability-critical codebases (e.g. hardware-facing apps) — engineer sign-off can't be skipped.
  • Context windows are finite (see concepts/context-window-as-token-budget) — dumping the entire 325+ line migration guide into every prompt wastes tokens on irrelevant steps.
  • Markdown guides are a stable starting point but not load-bearing — treating instructions as code means the guide eventually wants structure (argument parsing, per-step scope, reusable sub-steps).

Solution shape

  1. Start with a markdown migration guide. Capture patterns, edge cases, conventions iteratively as the team does a handful of migrations manually.
  2. Identify the risk-boundary checkpoints. Where must an engineer verify before the AI proceeds? (At Instacart: visual-parity check before cleanup.)
  3. Decompose into numbered steps clustered into stages. Each stage has a clear goal; each step within a stage is a single-purpose unit the AI can execute.
  4. Formalise into an Agent Skill (see systems/agent-skills) — structured format with step-scoped context, enabling progressive disclosure so the AI loads only what's relevant to the current step rather than the full guide.
  5. Place engineer verification gates at the checkpoints identified in step 2 — AI halts, engineer reviews, approves or corrects, AI resumes.
  6. Iterate the skill like code — version it, track changes across migrations, capture new edge cases, deprecate anti-patterns. See concepts/ai-instructions-as-code.

Canonical application — Instacart Caper Phase 3

The 2026-02-03 Instacart post describes a 17-step workflow clustered into four stages for Fragment → Compose migration:

Stage 1 — Analysis + Baselining

  • Identify Fragment type (Fragment vs DialogFragment).
  • Analyze XML layout + implementation.
  • Create Paparazzi baseline screenshot of the current UI. (Engineer checkpoint: confirm baseline captures intended visual state.)

Stage 2 — Compose Implementation

  • Create the new Compose View with identical UI.
  • Build Screen/Dialog structure following the Phase-1 parameterless / internal Composable split.
  • Set up dependency injection.
  • Add Compose previews.

Stage 3 — Verification + Integration

  • Automated visual-parity check: Paparazzi screenshot of the new Compose version diffed against baseline. (Engineer checkpoint: review diff, sign off on pixel parity — patterns/visual-parity-screenshot-gate.)
  • Update the nav graph to route to the new Compose route.
  • Run all tests, confirm no regressions.

Stage 4 — Cleanup

  • Remove old Fragment code.
  • Final verification run.

Instacart's post frames the progressive-disclosure win:

"Skills enable progressive disclosure of information, allowing the AI to access exactly what it needs at each step without overwhelming the context window."

Consequences

  • Predictable output quality — engineer checkpoints catch AI mistakes before they compound.
  • Context-window efficiency — progressive disclosure fits more signal per token.
  • Replicable across teams — the skill is the playbook; other teams run the same workflow.
  • Iteratively improving — the skill is versioned + improved across migrations, each iteration benefits the next.
  • Higher upfront investment than a one-shot script — you pay for the skill structure + checkpoint design.
  • Works best at scale — amortised over dozens of migrations; overkill for <10 instances.

Counter-indications

  • Creative / one-shot rewrites where a clean-slate reimplementation is feasible — see patterns/ai-driven-framework-rewrite + patterns/migration-as-agent-skill for the single-skill-one-migration shape.
  • Very small migration scope — overhead of skill design + checkpoint wiring dominates savings.
  • No structured skill runtime available — markdown guide + iterative AI prompting is the fallback shape; the Phase-2 Instacart workflow before skills emerged is the canonical example.

Seen in

  • sources/2026-02-03-instacart-migrating-to-jetpack-compose — canonical wiki instance. Instacart's Caper team ran Fragment → Compose migration via a 17-step AI skill with Paparazzi visual-parity gates, formalised from an earlier markdown migration guide, after 5–6 prior migrations made the workflow predictable.
Last updated · 319 distilled / 1,201 read