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-changes
3description: 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 Toolkit
4license: Apache-2.0
5metadata:
6 author: Juan Antonio Breña Moral
7 version: 0.18.0
8---
9
10# Avoid Breaking Changes
11
12Review planned repository changes for breaking-change and compatibility risk before implementation or release promotion. **This is an interactive SKILL**.
13
14**What is covered in this Skill?**
15
16- Command contract compatibility: names, inputs, owning agents, outputs, safeguards, installer registration, and command inventories
17- Skill routing compatibility: identifiers, metadata, descriptions, triggers, references, generated local output, and acceptance coverage
18- Generated-output ownership: XML/source files versus `.agents/skills`, public `skills/`, `.cursor/commands`, `.cursor/rules`, and `docs/`
19- Source and generator contracts: XML, XInclude, XSLT, Maven modules, schema expectations, and module validation
20- README, localized README, changelog, migration, and deprecation guidance
21- External and runtime contracts: APIs, schemas, data formats, configuration keys, persistence, CLI behavior, and CI expectations
22- Structured compatibility reports with severity-ranked findings and validation guidance
23
24## Constraints
25
26Keep the review evidence-based, read-only, and scoped to compatibility risk unless the user explicitly asks for implementation.
27
28- **MUST** read `references/056-design-avoid-breaking-changes.md` before producing compatibility guidance
29- **MUST** identify the source artifacts reviewed and the compatibility surfaces considered
30- **MUST** distinguish confirmed breaking changes, potential risks, non-breaking changes, and unknowns that need maintainer decision
31- **MUST** include migration, deprecation, validation, or release-note guidance for intentional breaking changes
32- **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
33- **MUST NOT** modify plans, specs, source files, generated outputs, or issue descriptions during review unless the user explicitly requests implementation
34
35## When to use this skill
36
37- Review breaking changes in this spec
38- Check compatibility risks
39- Avoid breaking changes in this OpenSpec change
40- Review migration impact before release
41- Assess command and skill compatibility
42- Find generated output compatibility risks
43- Review API schema configuration or data contract changes
44
45## Workflow
46
471. **Read the compatibility reference**
48
49Read `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.
50
512. **Inventory compatibility surfaces**
52
53Check 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.
54
553. **Classify findings**
56
57Classify each finding as `BREAKING`, `POTENTIALLY BREAKING`, `NON-BREAKING`, or `UNKNOWN`. Include the affected users, artifacts, contracts, and validation evidence or missing evidence.
58
594. **Recommend migration and validation**
60
61For each confirmed or potential risk, recommend deprecation, compatibility windows, migration notes, release-note updates, generator checks, focused tests, or owner decisions.
62
635. **Report the review outcome**
64
65Produce 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.
66
67## Reference
68
69For detailed guidance, examples, and constraints, see [references/056-design-avoid-breaking-changes.md](references/056-design-avoid-breaking-changes.md).
gabrielmoreira