machenjie data-api-contract-changer
Role
Support analysis-agent and task-agent for bounded data and public-contract changes.
- Analysis mode (
analysis-agent): Classify compatibility, migration, and coexistence requirements. - Task mode (
task-agent): Apply the accepted transition across producers and consumers.
When To Use
- API contract change
- schema or migration change
Do Not Use
- no data or public contract impact
- unrelated read-only analysis
Required Inputs
- contract evidence
- compatibility requirements
- Analysis mode (
analysis-agent): consumer inventory, deployed versions, and current schema or API behavior. - Task mode (
task-agent): accepted contract decision with producer, consumer, migration, and rollback checks.
Professional Decision Rules
- Treat API, event, schema, error, and data formats as consumer contracts with explicit compatibility windows.
- Prefer additive evolution; use expand, migrate, verify, and contract ordering for stateful changes.
- Identify old/new coexistence, defaults, nullability, versioning, replay, and rollback behavior.
- Validate producers and consumers, not only the changed implementation.
High-Value Gotchas
- A nullable or defaulted field can still break semantic compatibility.
- Rollback may fail after irreversible data contraction.
- Producer-only tests miss consumer breakage.
Execution Checklist
- Trace the changed field, schema, error, or event semantics through every known consumer.
- Choose an additive, versioned, or staged transition from coexistence and rollback evidence.
- Verify defaults, nullability, generated surfaces, replay, and old-client behavior.
- Analysis mode: select a transition from consumer and coexistence evidence.
- Task mode: apply the transition across generated and deployed consumer surfaces.
- Stop when consumer coverage or rollback feasibility remains unknown.
Stop / Escalation Conditions
- Stop implementation when compatibility class, known/unknown consumers, old-client behavior, generated artifact diff, migration order, rollback, validation command, or deprecation owner is implicit.
- Stop breaking changes that remove/rename/change type/semantics until versioning or expand/migrate/contract, migration guide, consumer notification, and rollback evidence are present.
- Stop schema or data changes when production table size, lock behavior, null/default semantics, old/new version skew, or rollback script is unknown.
- Stop external actions when generated clients, production data, external consumers, mobile lag, audit data, or releases require additional authority.
- Require current permission, redaction, approval, and freshness evidence before proceeding.
Output Contract
- Analysis mode (
analysis-agent): contract transition; consumer impact; migration and rollback model. - Task mode (
task-agent): producer and consumer changes; compatibility evidence; unverified consumers.
Targeted References
| Path | Type | Load when | Do not load when | Required by | Required output |
|---|---|---|---|---|---|
| checklist | decision-checklist | A bounded review needs concrete contract, pagination, migration, rollback, deprecation, and observability coverage | Consumer proof, generated diff, or performance/rollback tradeoff is the core risk | analysis-agent, task-agent | checklist-result, residual-risk |
| evidence patterns | evidence-pattern | Closure depends on consumer proof, generated artifact diff, migration/rollback evidence, deprecation/deletion, or stale contract validation | High-level routing is enough and evidence is not being closed | analysis-agent, task-agent | evidence-record, proof-limit, residual-risk |
| index | index | competing data api contract changer references require dependency, conflict, or output-fragment selection | the data api contract changer root or a task-named reference already resolves selection | analysis-agent, task-agent | reference-selection |
| solution optimality | targeted | A schema, API, event, version, migration, list/expansion, filter, or compatibility design has a material consumer, data-growth, or recovery tradeoff | The change is demonstrably additive and bounded with no affected consumer, storage, query, migration, or coexistence choice | analysis-agent, task-agent | selected-approach, residual-risk |