Test migration before committing: import 20-50 representative items and check every one for formatting, metadata, and link integrity

Why This Is a Rule

Migration tools and export/import functions routinely promise "seamless transfer" that turns out to be anything but. Markdown formatting breaks. Metadata fields map incorrectly. Internal links point to nonexistent targets. Embedded images lose their paths. You discover these problems after migrating 2,000 items — at which point fixing each item manually takes longer than the migration itself.

The 20-50 item test migration catches these problems before you commit. The sample must be representative: include items with different formatting (headings, lists, code blocks, tables), different metadata patterns (tags, dates, custom fields), internal links (both to other notes and to external URLs), and embedded content (images, files). Each imported item is examined against the original, not just spot-checked — a 50-item test with thorough examination takes 2-3 hours but saves weeks of post-migration cleanup.

The three inspection dimensions — formatting survival (does the visual structure reproduce correctly?), metadata preservation (do tags, dates, and properties transfer?), and link integrity (do internal and external links still work?) — cover the three most common migration failure modes. If all three pass across representative items, the full migration is likely to succeed.

When This Fires

• Before any tool migration, after selecting the destination tool
• Before starting Run old and new tools in parallel for 2-4 weeks during migration — new data to new tool, old data from old tool, end only when daily needs are confirmed's parallel period
• When evaluating whether a migration is feasible at all
• Complements Choose open portable formats (Markdown, CSV, JSON) over proprietary — migration cost compounds daily with every new piece of locked-in data (open format preference) with the verification that open formats actually transfer correctly

Common Failure Mode

Untested bulk migration: exporting 3,000 notes, importing them all at once, and discovering two weeks later that all internal links are broken. The fix requires re-importing or manually repairing 3,000 items. A 50-item test would have caught the link issue in 30 minutes.

The Protocol

(1) Select 20-50 items from your current tool that represent the diversity of your data: different formatting styles, metadata patterns, link types, and content types. (2) Export and import these items into the destination tool. (3) Examine every imported item against the original. Check: Formatting — do headings, lists, bold/italic, code blocks, and tables reproduce correctly? Metadata — do tags, dates, custom fields, and properties transfer? Links — do internal links point to correct targets? Do external URLs work? (4) Document any failures. Categorize them: Fixable (can be batch-corrected post-migration) vs. Blocking (fundamental incompatibility that can't be fixed). (5) If blocking failures exist → either find an alternative migration path or reconsider the tool choice. If only fixable failures → proceed to Run old and new tools in parallel for 2-4 weeks during migration — new data to new tool, old data from old tool, end only when daily needs are confirmed's parallel period, knowing what cleanup will be needed.