055 Design Parallel Change Agent Skill

Parallel Change Design

Guide Java Enterprise developers through Parallel Change for database migration scenarios. This is an interactive SKILL.

What is covered in this Skill?

• Deciding whether a database migration needs a compatibility window
• Sequencing database changes as expand, migrate, and contract deployable steps
• Preserving old and new application versions during rollout and rollback windows
• Handling column renames, type or data reinterpretation, large backfills, relationship-table changes, and index or uniqueness changes
• Explaining tradeoffs such as temporary dual paths, extra migrations, verification effort, and delayed cleanup
• Routing framework-specific implementation to Spring Boot, Quarkus, or Micronaut Flyway skills after the design approach is clear

Constraints

Use Parallel Change as a database migration design pattern, then hand off implementation details to the framework-specific migration skill when needed.

• MUST read references/055-design-parallel-change.md before applying Parallel Change guidance
• MUST explain expand, migrate, and contract as separate deployable steps when recommending Parallel Change
• MUST decide whether Parallel Change is needed before recommending framework-specific Flyway implementation details
• MUST recommend a simpler single migration when the change is additive, immediately safe, and does not require old and new application versions to coexist
• MUST describe the compatibility, data-preservation, verification, and cleanup tradeoffs of the chosen approach
• MUST use framework-specific Flyway skills for Spring Boot, Quarkus, or Micronaut implementation details after the migration strategy is selected

When to use this skill

• Apply Parallel Change to this database migration
• Use expand migrate contract for this schema change
• Plan a safe column rename migration
• Plan a zero-downtime database migration
• Should this Flyway migration use Parallel Change?
• Design a safe backfill and contract migration
• Decide if this schema change needs a compatibility window

Workflow

• Classify the Migration Risk

Read references/055-design-parallel-change.md, then identify the schema shape, data meaning, application read/write path, rollout window, rollback expectation, and production-data risk affected by the migration.

• Choose Parallel Change or Simpler Migration

Recommend Parallel Change when old and new application versions or data interpretations must coexist. Recommend a simpler forward-only migration when the change is additive, small, immediately safe, and does not require a compatibility window.

• Design Expand, Migrate, Contract

For Parallel Change, separate expand, migrate, and contract into independently deployable steps. Keep the old shape valid during expand and migrate; contract only after all deployed code and data have moved to the new shape.

• Plan Verification and Operations

Define previous-release fixture checks, row-count expectations, duplicate detection, backfill monitoring, rollback behavior, and cleanup ownership. Prefer production-dialect migration tests and production-like data samples where feasible.

• Route Framework Implementation

After the strategy is clear, use 313-frameworks-spring-db-migrations-flyway, 413-frameworks-quarkus-db-migrations-flyway, or 513-frameworks-micronaut-db-migrations-flyway for framework-specific Flyway dependencies, configuration, migration locations, and tests.

• Report the Migration Plan

Report the chosen approach, rejected alternative, expand/migrate/contract sequence or simpler migration, verification evidence, cleanup trigger, tradeoffs, skipped checks, and remaining risks.

Reference

For detailed guidance, examples, and constraints, see references/055-design-parallel-change.md.