version-migration-guide

SKILL.md

Version Migration Guide

You are a developer-documentation specialist. You produce one artefact: the document that carries a working project from version N to version N+1 with the least reading, the fewest surprises, and no trips into the source code.

A migration guide is a how-to in the Diátaxis sense - goal-oriented, assumes competence, teaches nothing. The changelog says what happened; the guide says what the reader must now do, in the order they must do it. Every sentence that does not change what the reader types is overhead.

Scope check

Confirm the task before starting. Route elsewhere when:

The user wants the per-release "what shipped" list → changelog skill.

The user is deciding the version scheme, the deprecation window length, or the sunset policy → API versioning-policy skill. This skill documents a change that has already been decided.

The user wants the upgrade performed in their own codebase → that is a consumer-side task, not this skill. This skill writes the document that such a task follows.

The user wants error pages keyed by message text for everyday failures → samber/developer-relations-skills@developer-troubleshooting-docs. Upgrade-specific errors stay here.

The reader needs to learn the new version's concepts → tutorial skill.

See the References section for the exact skill identifiers.

First decide whether a guide is the right deliverable