breaking-changes-management

Use this skill when behavior, interfaces, configuration, or compatibility contracts change in a way that can break consumers.

• Leverage native parallel subagent dispatch and 200k+ context windows where available.

Activation Conditions

Use symptom -> action triggers: when one matches, apply this skill and verify with the protocol below.

• Releasing a major version
• Renaming or removing public APIs
• Changing request or response shapes
• Replacing config keys, env vars, CLI flags, or file formats
• Writing migration notes, deprecation notices, or upgrade checklists

Workflow

1. Identify the exact consumer-visible break.
2. State who is affected and from which version.
3. Provide the replacement path or mitigation.
4. Add before/after examples.
5. Update CHANGELOG.md and any setup or usage docs that changed.

Required Outputs

• Changelog entry with a clear BREAKING label
• Migration guide with old usage, new usage, and upgrade steps
• Deprecation timeline if removal is delayed
• Validation notes for any examples or scripts that changed

<!-- MCP:START --> <!-- PORTABILITY:START -->

Cross-Client Portability

This skill is written to stay usable across GitHub Copilot, Claude Code, and Codex.

• GitHub Copilot: keep the folder in a Copilot-visible skill path or wrap the workflow in project instructions when folder discovery is unavailable.
• Claude Code: keep the folder in a local skills directory or a compatible plugin source.
• Codex: install or sync the folder into $CODEX_HOME/skills/breaking-changes-management and restart Codex after major changes.

<!-- PORTABILITY:END -->

MCP Availability And Fallback

Preferred MCP Server: None required

• Fallback prompt: "Use the Breaking Changes Management skill without MCP. Rely on its local instructions, bundled resources, standard shell or editor tools, and direct verification. Show the evidence used before concluding."
• Do not claim an MCP operation was used when the active host does not expose it.
• Treat local files, tests, rendered outputs, logs, or screenshots as the fallback evidence path.

<!-- MCP:END -->

Anti-Patterns

• Starting work before the plan or gate is clear: Execution drifts when success criteria are implied instead of explicit.
• Treating verification as optional cleanup: The last mile is where regressions and missing updates are usually hiding.
• Mixing planning, implementation, and release work in one jump: You lose the causal chain that explains why a change is safe.

Verification Protocol

Before claiming "skill applied successfully":

1. Pass/fail: The Breaking Changes Management workflow starts from explicit success criteria, constraints, and stop conditions.
2. Pass/fail: Required evidence is collected before any completion, approval, or readiness claim.
3. Pass/fail: The next action follows the documented gate order without skipping review or verification steps.
4. Pressure-test scenario: Apply the workflow under time pressure with one failing check and one tempting shortcut.
5. Success metric: Zero rationalizations; blocked, failed, or unverified work is reported as such.

Migration Checklist

• [ ] Old behavior described precisely
• [ ] New behavior described precisely
• [ ] Replacement path documented
• [ ] Upgrade steps ordered and testable
• [ ] Rollback or compatibility notes included
• [ ] README/setup docs updated if user-facing behavior changed

References & Resources

Documentation

• Deprecation Procedures - Deprecation wording, timelines, and migration guidance patterns

Scripts

• Migration Guide Scaffold - Generate a migration guide skeleton with version, impact, and step sections

Related Skills

• development-workflow: Use it when the workflow also needs planning, quality gates, and delivery tracking.
• code-quality: Use it when the workflow also needs two-stage review (spec compliance first, then code quality), maintainability, and refactoring guidance.
• systematic-debugging: Use it when the workflow also needs root-cause debugging before proposing fixes.
• test-driven-development: Use it when the workflow also needs test-first implementation and regression safety.