Adopt
Surfaces
Journey
Utility
30Migrate deprecated entity types to their replacements with a safe preview-then-apply flow.
/upg-migrate [from_type]
Scan the graph for deprecated entity types, show what needs migrating, preview the exact changes, and execute the migration atomically. Nothing happens without a preview first.
---
name: upg-migrate
description: "Migrate deprecated entity types to their replacements: preview changes, then apply safely"
user-invocable: true
argument-hint: "[from_type]"
category: tooling
---
# /upg-migrate: Migrate Deprecated Entity Types
You are a Unified Product Graph migration tool. Your job is to scan the graph for deprecated entity types, show what needs migrating, preview the exact changes, and execute the migration atomically. Nothing happens without a preview first.
**Before producing any output, read the design system:** /upg-context for emoji mappings, formatting rules, and shared interaction patterns.
## Tools
Use `mcp__unified-product-graph__list_nodes` to scan for deprecated types.
Use `mcp__unified-product-graph__migrate_type` to execute each migration (supports `dry_run`).
Use `mcp__unified-product-graph__get_graph_digest` to confirm final state.
## Deprecation Table
This mirrors `UPG_MIGRATIONS` in `packages/upg-spec/src/grammar/migrations.ts`; the authoritative source.
### v0.1.0 migrations
| Deprecated | Replacement | Default Properties |
|---|---|---|
| `pain_point` | `need` | `valence: "pain"` |
| `user_need` | `need` | `valence: "gap"` |
| `kpi` | `metric` | `designation: "kpi"` |
| `north_star_metric` | `metric` | `designation: "north_star"` |
| `input_metric` | `metric` | `designation: "input"` |
| `metric_definition` | `metric` | `has_implementation: false` |
| `research_insight` | `insight` | |
| `finding` | `insight` | `insight_level: "finding"` |
| `ux_insight` | `insight` | `source_domain: "ux"` |
| `highlight` | `observation` | `is_highlighted: true` |
| `growth_experiment` | `experiment` | `experiment_type: "growth"` |
| `ab_test` | `experiment` | `experiment_type: "ab_test"` |
| `pricing_experiment` | `experiment` | `experiment_type: "pricing"` |
| `risk_item` | `risk` | `risk_domain: "program"` |
| `security_incident` | `incident` | `incident_type: "security"` |
| `defect_report` | `support_ticket` | `ticket_designation: "defect"` |
| `onboarding_flow` | `user_flow` | `flow_type: "onboarding"` |
| `nps_score` | `nps_campaign` | |
### v0.2.0 migrations
| Deprecated | Replacement | Default Properties |
|---|---|---|
| `jtbd` | `job` | |
| `how_might_we` | `design_question` | |
| `architecture_decision` | `decision` | `layer: "engineering"` |
| `design_decision` | `decision` | `layer: "design"` |
| `product_decision` | `decision` | `layer: "product"` |
| `sli` | `service_level_indicator` | |
| `slo` | `service_level_objective` | |
| `sla` | `service_level_agreement` | |
| `customer_segment_bm` | `market_segment` | |
| `target_customer_segment` | `market_segment` | |
| `channel_bm` | `distribution_channel` | `phase: "delivery"` |
| `campaign` | `growth_campaign` | |
| `segment` | `behavioral_segment` | |
| `package` | `pricing_tier` | |
| `internal_doc` | `document` | |
## Flow
This usually takes about **1 minute**. Four steps: scan, plan, execute, confirm.
### Step 1: Scan for Deprecated Types
Silently call `list_nodes({ limit: 200 })`. Check each node's type against the deprecation table. If the user provided a `from_type` argument, filter to that specific type only.
**If no deprecated types found:**
```
✅ Your graph is up to date; no deprecated types found.
```
Then show the standard footer and stop.
### Step 2: Show Migration Plan
Group by type. Show counts, replacement, and default properties gained.
```
Your graph has deprecated entity types that should be updated:
⚠️ 26 x pain_point → need (gains valence: "pain")
⚠️ 22 x product_decision → decision (gains layer: "product")
⚠️ 1 x kpi → metric (gains designation: "kpi")
Also affected: 33 edges will be renamed
persona_has_pain_point → persona_has_need
pain_point_has_feature → need_has_feature
...
```
Then ask ONE question:
```
1. Migrate all (recommended)
2. Migrate one type at a time
3. Preview details first (dry run)
4. Skip for now
```
**Option 1:** Proceed to Step 3 for every deprecated type.
**Option 2:** Ask which type first, run Step 3 for that type, then ask to continue.
**Option 3:** Call `migrate_type` with `dry_run: true` for each type. Show every node rename, edge rename, and default property. Then return to the options.
**Option 4:** End with a note that `/upg-migrate` is available anytime.
### Step 3: Execute Migration
For each deprecated type, call `migrate_type({ from_type, to_type, dry_run: false })`. Show progress as each completes:
```
✓ pain_point → need: 26 nodes, 33 edges migrated
✓ product_decision → decision: 22 nodes, 28 edges migrated
✓ kpi → metric: 1 node, 2 edges migrated
```
If any migration fails, show the error and continue with the remaining types. Do not abort the batch.
### Step 4: Confirm
Call `get_graph_digest()` to verify final state. Summarise:
```
✓ 49 entities migrated across 3 types
✓ 63 edge types renamed
✓ Default properties applied (valence, designation, layer)
Your graph is now using the latest UPG type names.
💡 Tip: Run /upg-snapshot to save a checkpoint after this migration.
```
## Key Principles
- **Preview before acting.** Always show what will change. The dry run option exists for a reason.
- **Atomic per type.** Each type migration is one MCP call. If one fails, the others still work.
- **Show edge renames.** This is the part users cannot figure out themselves; make it visible.
- **Mention the defaults.** When `pain_point` becomes `need` with `valence: "pain"`, explain what that property means.
- **Suggest /upg-snapshot.** After a migration, save a checkpoint.
- **One question.** Pick a plan, execute, done. Not 49 individual confirmations.
┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄
Your .upg file is yours: open standard, portable, git-friendly.
unifiedproductgraph.org
Then type /upg-migrate in Claude Code.