---

name: ramp-migration-deep-dive description: >- Plan and execute a controlled migration from a legacy expense or card platform to Ramp with identity, spend-control, open-item, and accounting reconciliation. Use when an enterprise cutover requires parallel run and rollback. Trigger with "migrate to Ramp" or "Ramp cutover plan". allowed-tools: Read,Glob,Grep,Write,Edit version: 2.0.0 argument-hint: "[integration-or-environment]" model: inherit effort: high author: Jeremy Longshore jeremy@intentsolutions.io license: MIT compatibility: Requires current Ramp Developer API documentation and approved access for any live financial, card, identity, accounting, application, or configuration change tags: [saas, ramp, migration, cutover, reconciliation]

Legacy Expense Platform to Ramp Migration

Overview

Treat the migration as a sequence of independently reconciled cohorts, not a bulk import. Map business meaning before identifiers, keep legacy and Ramp authority explicit during coexistence, and retire the old platform only after financial close.

Prerequisites

• Identify the Ramp application, environment, business entities, affected data and workflows, accountable owner, and rollback boundary.
• Read references/official-docs.md and re-check endpoint schemas, scopes, limits, and support status before a live operation.
• Use synthetic fixtures or Ramp sandbox until production access and business effects are explicitly approved.
• Prepare approved secret storage and a sanitized evidence location.

Current Contract

• Ramp users, entities, funds, cards, transactions, bills, reimbursements, vendors, and accounting objects have distinct relationships and endpoint contracts.
• Current virtual-card authority is fund-backed and governed through spend controls; legacy card abstractions should not be mapped one-to-one without review.
• Accounting connections distinguish Ramp identifiers from ERP remote identifiers and require explicit sync receipts.
• Webhook coverage and incremental filters vary by object, so migration reconciliation cannot depend on one universal change feed.

Instructions

1. Inventory legacy tenants/entities, users, roles, cards, limits, policies, vendors, open expenses, bills, reimbursements, receipts, accounting mappings, integrations, and retention duties.

2. Create a signed semantic mapping for each object and state, including unsupported values, money/currency conversion, ownership, destination ID, and disposition.

3. Build sandbox fixtures for normal, boundary, duplicate, missing-owner, invalid-currency, closed-period, and rollback cases; validate against current Ramp schemas.

4. Migrate one entity or department cohort, run parallel read/reconciliation, and hold card or accounting writes until users, controls, balances, and mappings are approved.

5. Cut over with frozen checkpoints and named authority, reconcile open and late-arriving items through financial close, then revoke legacy access under retention policy.

Tool Discipline

• Use Glob to locate candidate code, manifests, fixtures, and evidence without widening scope.
• Use Grep to find relevant endpoints, fields, permissions, identifiers, errors, and stale assumptions.
• Use Read to inspect the smallest required local files and authoritative evidence.
• Use Write only for a new approved local draft, test, configuration, or evidence artifact.
• Use Edit only for a bounded approved change with a known rollback.
• Local file tools do not authorize a Ramp operation or replace owner approval.

Approval Boundaries

Business and finance owners approve semantic mappings and cutover; security/privacy approve identity and data movement; accounting approves balances, mappings, and final close.

Output

A source inventory, semantic map, cohort plan, exception ledger, ID crosswalk, sandbox proof, parallel-run reconciliation, cutover/rollback record, and retirement evidence.

Error Handling

Condition	Response
A legacy state has no Ramp equivalent	Quarantine it with an owner and explicit transform, manual handling, or no-migrate decision.
A user or entity mapping is ambiguous	Stop the cohort; do not assign spend authority by name similarity.
Late transactions arrive after cutover	Apply the frozen coexistence rule, migrate or settle once, and reconcile both systems through close.

Examples

Example 1

Migrate one subsidiary's users and recurring software cards into approved Funds while keeping the legacy issuer read-only for late settlement.

Example 2

Move open reimbursements and vendor mappings, reconcile ERP references, and retire the old export only after period close.

Validation

• Every source record has one destination, exception, or approved retirement disposition.
• Identity, entity, currency, amount, and accounting mappings reconcile independently.
• No spend authority or production write is enabled before approval.
• Rollback and coexistence cover late, duplicated, and in-flight records.

Resources

• Official documentation and contract notes
• Re-check the dated contract and current OpenAPI schema before any live request.
• Treat unresolved vendor behavior, authority, or financial state as a stop condition.