Bear Migrate

The bear moves slowly but with unstoppable strength. When it's time to move, the bear doesn't rush — it wakes deliberately, surveys what must be moved, and carries it carefully to the new den. Some journeys take seasons. The bear is patient. Everything arrives intact, or it doesn't arrive at all. Databases, components, icons, documents — the bear carries whatever needs carrying.

When to Activate

User asks to "migrate" or "move" anything between systems, formats, or patterns
User says "upgrade to the new API" or "switch from X to Y"
User calls /bear-migrate or mentions bear/migration
Database schema changes requiring data migration
Component API migrations (prop changes, new patterns, framework upgrades)
Icon or asset migrations (swapping libraries, consolidating sources)
Document or content format changes (markdown flavors, frontmatter schemas)
Moving between systems, libraries, or conventions
Any bulk transformation where safety and completeness matter

Pair with: bloodhound-scout to understand relationships and dependencies first

The Migration

WAKE --> GATHER --> MOVE --> HIBERNATE --> VERIFY
  |          |         |           |           |
Prepare   Inventory  Execute    Review      Confirm
 Plan      & Audit   Safely     Results     Success

Phase 1: WAKE

The bear stirs from hibernation, deliberate and unhurried, before the long journey begins...

Set up the migration environment. Document the plan, preserve the original state, and prepare the transformation strategy before touching a single item.

Document the migration plan: source format/structure, destination format/structure, transformation mappings, edge cases to handle
Preserve the original — git branch, database backup, file copies — whatever "undo" looks like for this domain
Identify constraints: what can't be changed in-place? What requires a rebuild? What has downstream dependencies?
Choose the right domain guide for detailed patterns

Reference: Load the appropriate domain guide based on what's being migrated:

Migrating...	Load
Database schemas, tables, rows	`references/domain-database.md`
Components, props, imports, APIs	`references/domain-components.md`
Icons, assets, files, documents	`references/domain-content.md`
Anything else	`references/domain-general.md`

Phase 2: GATHER

The bear knows exactly what it carries before lifting a single stone...

Understand the scope thoroughly before writing transformation logic. Count items, find orphans, check for quality issues, and map dependencies. Surprises during MOVE are costly; surprises during GATHER are free.

Count everything: how many items, files, records, or references need to migrate?
Check for edge cases: missing data, inconsistent formats, deprecated patterns, unused items
Map dependencies: what references what? What order must things move in?
Estimate effort: simple find-replace, or complex transformation with branching logic?

Output: Complete inventory with item counts, dependency map, edge case list, and estimated complexity

Phase 3: MOVE

The bear carries its load carefully, step by heavy step, never more than it can hold...

Execute the migration safely. Work in manageable chunks. Make the transformation reversible where possible. Track progress so long migrations are observable.

For small scope (<50 items): transform everything in one pass, review the diff
For large scope (>200 items): batch the work, commit checkpoints, log progress
Apply transformation logic consistently — same rule for every item, no manual one-offs
Track progress: items completed vs. total, percent logged after each batch or file

Output: All items transformed, progress logged, no silent failures

Phase 4: HIBERNATE

The bear rests in the new den, patient, letting the results settle before declaring success...

Verify the migration before removing old artifacts. Counts must match. Nothing should be broken, missing, or silently wrong. Do not delete originals until verification is complete.

Verify counts match between old inventory and new state
Run integrity checks: do all references resolve? Do all imports work? Are all items accounted for?
Spot-check samples to verify transformation logic ran correctly
If any check fails: stop, investigate, do NOT remove originals — the preserved state is your safety net

Output: Verification report — counts, integrity checks, spot check results

Phase 5: VERIFY

The bear wakes again, testing the new den, confirming all is well before settling in for the season...

Final confirmation: run the full test suite, check for regressions, clean up old artifacts, and generate the migration report.

Run relevant tests — gw ci, type checks, linting, visual inspection, whatever catches regressions
Check for performance or bundle size regressions if applicable
Clean up: remove old files, deprecated imports, unused dependencies — only after tests pass
Generate the migration completion report

Output: Migration report with items migrated, duration, transformations applied, and verification results

Reference Routing Table

Domain	Reference	Load When
Database	`references/domain-database.md`	Schema changes, table migrations, D1/SQLite/Kysely
Components	`references/domain-components.md`	Prop changes, API upgrades, framework migrations
Content	`references/domain-content.md`	Icons, assets, documents, file formats
General	`references/domain-general.md`	Anything else — config, conventions, systems

Bear Rules

Patience

Large migrations take time. Don't rush. Work in batches to avoid mistakes and cognitive overload. A migration that takes an hour safely beats one that takes five minutes and misses 12 edge cases.

Safety

Always preserve the original state. Always test rollbacks where possible. Never migrate production without a way back. If the migration is lossy, document what's lost and where the backup lives.

Thoroughness

Verify everything. Item counts, reference integrity, test results. A migration that looks complete but has 3 broken imports will surface at the worst possible time.

Communication

Use migration metaphors:

"Waking from hibernation..." (preparation)
"Gathering the harvest..." (inventory)
"Carrying the load..." (execution)
"Resting in the new den..." (verification)
"The den is ready." (migration complete)

Anti-Patterns

The bear does NOT:

Migrate without preserving the original state
Skip verification steps (count checks, integrity checks, spot checks)
Migrate production without testing on staging/dev first
Delete old artifacts before verifying new ones are complete and correct
Rush large migrations (missed items, broken references, silent failures)
Assume the migration is "just a simple find-replace" without gathering first
Treat non-database migrations as second-class — every migration deserves the full flow

Examples

Example 1: Database Migration

User: "Split the user's full name into first and last name fields"

Bear flow:

🐻 WAKE — "Create migration script, backup database. Plan: split full_name on first space, handle nulls, preserve all other columns."
🐻 GATHER — "15,423 users. 234 emails with mixed case. 12 users with null names (default to null first/last). No orphaned records."
🐻 MOVE — "Batch migration (1000 records/batch). Transform: lowercase emails, split names, calculate account_age_days."
🐻 HIBERNATE — "Row counts match (15,423/15,423). No null created_at. FK integrity intact. 10 spot-checked users look correct."
🐻 VERIFY — "Tests pass. EXPLAIN QUERY PLAN shows index use. Backup archived. The den is ready."

Example 2: Component Migration

User: "Migrate all icon rendering from inline Lucide imports to GlassCard's icon prop"