Event Schema Evolution Planner

What this skill does

Takes a current event schema and a desired future schema, produces a step-by-step evolution plan that keeps existing consumers working through the transition. Each step is provably backwards-compatible; only the final step retires deprecated fields.

Inputs

• current_schema: Avro, JSON Schema, or Protobuf source for the current shape.
• target_schema: the desired final shape.
• Optional consumer_inventory: a list of consumer service names with their last-deploy date.
• Optional deprecation_window_days: time consumers have to migrate (default 90).

Steps

1. Diff the two schemas. For each field, classify: added (target only), removed (current only), type-changed, renamed (heuristic: type identical, name similar).
2. Apply the additive-only rule:
   • Added optional fields with defaults: ship in step 1.
   • Removed fields: do NOT remove now; mark deprecated: true in step 1, remove in the final step after the deprecation window.
   • Type changes: never compatible directly. Plan a parallel new field with the new type (step 1), backfill (step 2), retire old field (final).
   • Renames: ship as new optional field plus old field as deprecated alias.
3. Add a schema_version integer to the schema if not present; bump it in each step.
4. Emit step 1: the schema with additions and deprecations.
5. Emit step 2: required-only changes after consumers have adopted (timestamp step1_date + deprecation_window_days).
6. Emit step 3: the final target schema with deprecated fields removed.
7. For each step, compute a compatibility level (e.g., Confluent's BACKWARD, FORWARD) and check that the chosen registry mode allows it.
8. Produce a consumer migration checklist: per consumer, list which fields they need to start writing/reading.
9. Save the plan as schema-evolution-plan.md with one section per step.

Output

schema-evolution-plan.md containing the three steps, each with the resulting schema (fenced), a compatibility verdict, and a date. Plus an Annex listing per-consumer action items. Stdout prints any unresolved migrations (renames the heuristic flagged ambiguous).

Verification

For each step's schema, run the Avro / Protobuf compatibility check (schema-registry-cli or protoc --fatal_warnings) against the previous step; the check must pass. Replay a sample of producer messages from the current schema against step 1's reader; deserialization must succeed. If the consumer inventory is missing dates or older than 1 year, extend the deprecation window proportionally rather than retire silently.

Edge cases

• Schema with deeply nested unions: changes inside a union member can be silently breaking; flag and route through manual review.
• Field whose semantics changed but name and type didn't: cannot be detected automatically; rely on a change_notes input or refuse without one.
• Cross-tenant consumers (no inventory): default to a 180-day deprecation window and document the assumption.
• Producer hasn't started emitting the new field by step 2's date: re-emit step 2 with the date pushed; do not advance to step 3.