machenjie version-compatibility
Registry Trigger
Use when
- assess backward compatibility deprecation version negotiation and client migration
Do not use when
- no task-local version compatibility decision is required
Skill Role
Define consumers, compatibility dimensions, mixed-version behavior, retirement, rollback readability, and evidence. Exclude contract design, migration execution, and release authority.
High-Value Rules
- Inventory evidence-backed consumers and skew. Include services, installed clients, partners, events, stored data, caches, jobs, scripts, libraries, and rollback versions.
- Classify compatibility by behavior. Evaluate source, binary, wire, schema, persisted-data, config, operational, and semantic compatibility; additive changes can break strict consumers.
- Design mixed-version coexistence. Define old/new writer-reader behavior, defaults, unknown values, ordering, activation, and partial rollout from the observed upgrade boundary.
- Select migration from constraints. Compare versioning, negotiation, additive bridge, dual read/write, expand-contract, translation, and coordinated cutover without a universal sequence.
- Treat errors, defaults, enums, and timing as contract. Check retry/timeout meaning, error shape, new values, omissions, activation order, and schema-invisible behavior.
- Make retirement evidence-based. Name usage signals, owner, deprecation communication, residual stored data or messages, and the removal condition.
- Preserve rollback readability. Show whether old code safely reads and acts on new state and side effects; otherwise define exposure limits and forward-repair ownership.
Anti-Patterns
- Assuming consumers upgrade together or deriving their window from producer speed.
- Calling added fields non-breaking despite changed defaults, validation, matching, or behavior.
- Removing a bridge by calendar without usage, stored-data, queue, and rollback evidence.
Stop Conditions
Escalate when consumers or skew are unknown, versions cannot coexist, rollback cannot interpret new state, long-lived clients lack adoption, or retirement evidence is unavailable. Also escalate when compatibility affects public, regulated, financial, permission, or irreversible behavior.
Output Contract
- compatibility decision with consumer inventory, compatibility dimensions, mixed-version matrix, migration mechanism, retirement evidence, rollback limits, proof gaps, and residual owners
Targeted References
| Path | Type | Load when | Do not load when | Required by | Required output |
|---|---|---|---|---|---|
| checklist | decision-checklist | mixed-version failures lack negative-path coverage | compatibility tests cover triggered boundaries | analysis-agent, task-agent, review-agent | checklist-result, residual-risk |
| compatibility benchmarks | benchmark-pattern | migration policy remains unresolved | no mixed-version consumers are affected | analysis-agent, task-agent, review-agent | option-comparison, selected-approach |
| evidence patterns | evidence-pattern | consumer evidence may be stale | current artifacts prove consumer behavior | analysis-agent, task-agent, review-agent | evidence-record, proof-limit, residual-risk |