Technology Migration

Pattern

Manage multi-phase tech migrations with clear deprecation paths and team coordination.

The Problem

Technology migrations are messy. You've decided to move from React Class Components to Hooks, or from REST to GraphQL, or from Postgres to CockroachDB.

The decision is made, but the migration takes months. During that time:

New team members don't know what's deprecated
Teams build on the old tech "just this once"
Nobody knows which services are migrated vs. blocked
The original decision gets forgotten or misremembered

The Pattern

Create the Migration Decision

Document the core decision: "Migrate from X to Y." This is your anchor.

Example:

"Migrate from Redux to React Query for server state management"

Set importance to Anchor or Committeddepending on how firm the decision is.

Create Deprecation Decisions

For each deprecated technology/pattern, create a decision that documents what's being phased out.

Example:

"Redux is deprecated for new features"

Link this with supersedes to the migration decision.

Create Phase Decisions

Break the migration into phases. Each phase is its own decision with clear scope and criteria.

Phase 1: New features use React Query

Phase 2: Migrate UserProfile domain

Phase 3: Migrate Checkout domain

Phase 4: Remove Redux dependency

Link phases with depends_on to show sequence.

Use Domains for Scope

Create a domain for the migration (e.g., "Redux Migration") and assign all related decisions to it.

This lets you filter the graph to just migration-related decisions, hiding the noise.

Track Progress with Statuses

As phases complete, conclude them. The graph shows migration progress at a glance:

Approved = Done

Active = In Progress

Blocked = Dependency issue

What the Graph Looks Like

Redux → React Query Migration

├── [Anchor] Migrate to React Query

│ ├── supersedes → Redux is deprecated

│ └── enables → Phase 1: New features

├── [Approved] Phase 1: New features use RQ

│ └── enables → Phase 2

├── [Active] Phase 2: Migrate UserProfile

│ ├── depends_on → Phase 1

│ └── enables → Phase 3

├── [Draft] Phase 3: Migrate Checkout

│ └── depends_on → Phase 2

└── [Draft] Phase 4: Remove Redux

└── depends_on → Phase 3

Anyone looking at this graph knows exactly where the migration stands, what's next, and what's blocking.

Anti-Patterns to Avoid

One giant migration decision

Don't put everything in one decision. It becomes a wall of text that nobody reads. Break it into phases.

No deprecation decision

If you don't explicitly document what's deprecated, people keep using it. Make the deprecation a first-class decision.

Missing dependency links

Phase 3 can't start until Phase 2 is done? Make that explicit with depends_on. Don't rely on people reading the decisions in order.

Using Briefings

Generate briefings from migration decisions for different audiences:

Onboarding Guide for new engineers: "We're in the middle of migrating to React Query. Here's what you need to know."
Executive Summary for leadership: "Migration is 60% complete. Phase 2 on track for Q3."
Technical Digest for the team: Weekly update on migration progress and blockers.

Git Providers

Cross-Team Conflicts

Command Palette