Avoid Breaking Changes

Avoid Breaking Changes

Review planned repository changes for breaking-change and compatibility risk before implementation or release promotion. This is an interactive SKILL.

What is covered in this Skill?

• Command contract compatibility: names, inputs, owning agents, outputs, safeguards, installer registration, and command inventories
• Skill routing compatibility: identifiers, metadata, descriptions, triggers, references, generated local output, and acceptance coverage
• Generated-output ownership: XML/source files versus .agents/skills, public skills/, .cursor/commands, .cursor/rules, and docs/
• Source and generator contracts: XML, XInclude, XSLT, Maven modules, schema expectations, and module validation
• README, localized README, changelog, migration, and deprecation guidance
• External and runtime contracts: APIs, schemas, data formats, configuration keys, persistence, CLI behavior, and CI expectations
• Structured compatibility reports with severity-ranked findings and validation guidance

Constraints

Keep the review evidence-based, read-only, and scoped to compatibility risk unless the user explicitly asks for implementation.

• MUST read references/056-design-avoid-breaking-changes.md before producing compatibility guidance
• MUST identify the source artifacts reviewed and the compatibility surfaces considered
• MUST distinguish confirmed breaking changes, potential risks, non-breaking changes, and unknowns that need maintainer decision
• MUST include migration, deprecation, validation, or release-note guidance for intentional breaking changes
• MUST respect repository source ownership: edit XML and source docs, regenerate generated output through documented workflows, and avoid direct generated-output edits unless the repository explicitly owns that file
• MUST NOT modify plans, specs, source files, generated outputs, or issue descriptions during review unless the user explicitly requests implementation

When to use this skill

• Review breaking changes in this spec
• Check compatibility risks
• Avoid breaking changes in this OpenSpec change
• Review migration impact before release
• Assess command and skill compatibility
• Find generated output compatibility risks
• Review API schema configuration or data contract changes

Workflow

1. Read the compatibility reference

Read references/056-design-avoid-breaking-changes.md, then identify the source artifacts to review, their authority, and whether the request is read-only review or approved implementation.