Change impact and compatibility
Maps compatibility risk across interfaces and stored or queued data, then orders changes so existing consumers can transition safely.
compatibility-change-impact
Agents using this skill
When is it useful?
Use when old and new application versions must coexist during a structural change.
What does it help you do?
- Inventories interfaces, persisted records, queued messages and configuration contracts.
- Plans dual support before migrating consumers and removing obsolete formats.
- Checks that errors, transaction boundaries and side effects retain intended behavior.
Try asking this
Plan renaming a job payload field while old workers and queued jobs still exist. Process old and new payloads during the transition. Specify when every producer and worker supports the new field before removing the old one.
Detailed documentation
Read the skill’s original instructions, examples and checks in their authored language.
Show less
Compatibility & Change Impact Analysis
A refactoring that compiles locally can still break external API consumers, in-flight background jobs, cached payloads, database rolling deployments or dynamic framework bindings. Evaluate every boundary crossed by the change before altering signatures or structures.
1. Contract & Boundary Inventory
Check every surface where the modified code interacts with the outside world or persisted state:
- Public & internal APIs: HTTP endpoints, GraphQL fields, RPC methods, WebSocket/IPC messages, CLI flags and exit codes, and exported package symbols.
- Persisted & in-flight data:
- Database columns, JSONB blobs, enum values and migration compatibility with currently running code.
- Queued job payloads, scheduled task parameters and event-bus messages already waiting in Redis/brokers during deployment.
- Browser
localStorage/IndexedDB, mobile client caches and server-side cache entries written by the previous version.
- Configuration & environment contracts: environment variable names, config file schemas, feature flag keys and default values.
2. Expand-and-Contract Across Version Boundaries
When a contract must change across services, clients or persisted state, never make an abrupt breaking swap in a single step:
- Expand (Dual Support):
- Accept both the old and new input formats/parameters (e.g., read new field with fallback to legacy field).
- Emit or populate backward-compatible outputs so existing consumers continue working.
- Migrate Consumers & State:
- Update internal callers, frontend/mobile clients or background job producers to use the new contract.
- Backfill or migrate persisted records and drain in-flight legacy queue payloads.
- Contract (Clean Removal):
- Remove the compatibility adapter, alias or deprecated field only after verifying that all consumers and persisted payloads have transitioned.
3. Error, Side-Effect & Performance Parity
Preserve operational invariants that callers implicitly rely on:
- Error semantics: keep HTTP status codes, domain error codes, exception types and retryability classifications stable unless an explicit contract change is agreed.
- Idempotency & transaction boundaries: splitting a function must not accidentally move a database write outside its transaction or cause an external side effect to fire twice on retry.
- Performance & algorithmic complexity: ensure decomposing a module does not replace a single batched query with an $N+1$ loop across an abstraction boundary or introduce unnecessary deep cloning on hot paths.
4. Rollout Ordering & Rollback Safety
- Determine whether the change is single-commit safe (purely internal with all callers updated atomically) or requires a multi-stage transition (schema -> code -> backfill -> cleanup).
- Verify that if the deployment is rolled back to the previous version, existing data and in-flight jobs remain readable.
- Document any temporary compatibility shims, deprecation notices and the concrete condition for removing them, and align cross-cutting impacts with the architect and the technical writer.
Included files 1
SKILL.md