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
- 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.
- Inventory compatibility surfaces
Check commands, skills, generated outputs, XML/source ownership, README/docs, tests, CI/build gates, external contracts, runtime behavior, data/configuration contracts, and release or migration guidance relevant to the proposed change.
- Classify findings
Classify each finding as BREAKING, POTENTIALLY BREAKING, NON-BREAKING, or UNKNOWN. Include the affected users, artifacts, contracts, and validation evidence or missing evidence.
- Recommend migration and validation
For each confirmed or potential risk, recommend deprecation, compatibility windows, migration notes, release-note updates, generator checks, focused tests, or owner decisions.
- Report the review outcome
Produce a concise compatibility report with reviewed sources, risk summary by surface, severity-ranked findings, recommended validation, and a clear no-risk statement when no breaking-change risks are found.
Reference
For detailed guidance, examples, and constraints, see references/056-design-avoid-breaking-changes.md.
1---2name: 056-design-avoid-breaking-changes3description: Use when you need to review a plan, OpenSpec change, specification, or implementation proposal for breaking-change risk across commands, skills, generated outputs, XML sources, README/docs, tests, CI, APIs, schemas, configuration, data, migration, and release guidance. This should trigger for requests such as 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. Part of Plinth Toolkit4license: Apache-2.05---6# Avoid Breaking Changes
7
8Review planned repository changes for breaking-change and compatibility risk before implementation or release promotion. **This is an interactive SKILL**.
9
10**What is covered in this Skill?**
11
12- Command contract compatibility: names, inputs, owning agents, outputs, safeguards, installer registration, and command inventories
13- Skill routing compatibility: identifiers, metadata, descriptions, triggers, references, generated local output, and acceptance coverage
14- Generated-output ownership: XML/source files versus `.agents/skills`, public `skills/`, `.cursor/commands`, `.cursor/rules`, and `docs/`
15- Source and generator contracts: XML, XInclude, XSLT, Maven modules, schema expectations, and module validation
16- README, localized README, changelog, migration, and deprecation guidance
17- External and runtime contracts: APIs, schemas, data formats, configuration keys, persistence, CLI behavior, and CI expectations
18- Structured compatibility reports with severity-ranked findings and validation guidance
19
20## Constraints
21
22Keep the review evidence-based, read-only, and scoped to compatibility risk unless the user explicitly asks for implementation.
23
24- **MUST** read `references/056-design-avoid-breaking-changes.md` before producing compatibility guidance
25- **MUST** identify the source artifacts reviewed and the compatibility surfaces considered
26- **MUST** distinguish confirmed breaking changes, potential risks, non-breaking changes, and unknowns that need maintainer decision
27- **MUST** include migration, deprecation, validation, or release-note guidance for intentional breaking changes
28- **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
29- **MUST NOT** modify plans, specs, source files, generated outputs, or issue descriptions during review unless the user explicitly requests implementation
30
31## When to use this skill
32
33- Review breaking changes in this spec
34- Check compatibility risks
35- Avoid breaking changes in this OpenSpec change
36- Review migration impact before release
37- Assess command and skill compatibility
38- Find generated output compatibility risks
39- Review API schema configuration or data contract changes
40
41## Workflow
42
431. **Read the compatibility reference**
44
45Read `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.
46
472. **Inventory compatibility surfaces**
48
49Check commands, skills, generated outputs, XML/source ownership, README/docs, tests, CI/build gates, external contracts, runtime behavior, data/configuration contracts, and release or migration guidance relevant to the proposed change.
50
513. **Classify findings**
52
53Classify each finding as `BREAKING`, `POTENTIALLY BREAKING`, `NON-BREAKING`, or `UNKNOWN`. Include the affected users, artifacts, contracts, and validation evidence or missing evidence.
54
554. **Recommend migration and validation**
56
57For each confirmed or potential risk, recommend deprecation, compatibility windows, migration notes, release-note updates, generator checks, focused tests, or owner decisions.
58
595. **Report the review outcome**
60
61Produce a concise compatibility report with reviewed sources, risk summary by surface, severity-ranked findings, recommended validation, and a clear no-risk statement when no breaking-change risks are found.
62
63## Reference
64
65For detailed guidance, examples, and constraints, see [references/056-design-avoid-breaking-changes.md](references/056-design-avoid-breaking-changes.md).
gabrielmoreira