{
  "schema_version": 2,
  "kind": "shortening-method",
  "format": "agent-skill",
  "id": "migration-guide",
  "name": "Migration guide",
  "category": "Technical",
  "summary": "Reduce upgrade instructions to the changes users must make in order.",
  "use_cases": [
    "Version upgrade guides",
    "Breaking-change instructions"
  ],
  "word_count": 150,
  "url": "https://sho.rten.it/methods/migration-guide/",
  "instructions_url": "https://sho.rten.it/methods/migration-guide/SKILL.md",
  "skill_url": "https://sho.rten.it/methods/migration-guide/SKILL.md",
  "json_url": "https://sho.rten.it/methods/migration-guide/llms.txt",
  "plain_text_url": "https://sho.rten.it/methods/migration-guide/prompt.txt",
  "license": "MIT",
  "sources_url": "https://sho.rten.it/sources/#migration-guide",
  "skill_name": "migration-guide",
  "skill_description": "Reduce upgrade instructions to the changes users must make in order. Use for Version upgrade guides, Breaking-change instructions.",
  "agents_md_url": "https://sho.rten.it/methods/migration-guide/AGENTS.md",
  "sources": [],
  "instructions": "Condense the supplied migration guide for a user moving between named versions. Preserve the sequence that makes the change safe and compatible.\n\nLead with the affected versions and who must act. Separate prerequisites, required edits, validation, and rollback when the source supplies them. Keep old-to-new mappings, exact identifiers, changed defaults, compatibility windows, backup requirements, and irreversible steps. Retain exceptions for users who do not need a change.\n\nRemove release marketing, repeated background, and unchanged behavior that does not affect migration. Combine related edits without hiding their order. A suggested step remains suggested; a required step remains required. Do not invent commands, assume a backup exists, or promise that rollback restores deleted data.\n\nOutput a short scope statement and numbered steps. Add a compact mapping table if several names change. Include supplied validation and rollback limits. This is a rewrite only: do not perform the upgrade or claim that it passed.",
  "example": {
    "context": "Client library breaking change",
    "before": "This guide is for applications upgrading Client Kit from 4.x to 5.0 that use local token storage. Applications that already supply their own tokenStore are not affected. Before upgrading, export the existing token database. In 5.0, the constructor option persistTokens is removed; replace persistTokens: true with tokenStore: new FileTokenStore(path). Use the same database path as before. Start one test session and confirm that its saved token is loaded after restart. Do not delete the export until this check passes. Version 4.x cannot read a database after 5.0 has written it; rollback requires restoring the export.",
    "after": "Scope: Client Kit 4.x → 5.0 with local token storage. Existing custom tokenStore users need no change.\n1. Before upgrading, export the token database.\n2. Replace persistTokens: true with tokenStore: new FileTokenStore(path), using the existing path.\n3. Start a test session. Restart and confirm its saved token loads.\n4. Keep the export until the check passes.\nRollback: 4.x cannot read a database written by 5.0. Restore the export.",
    "must_preserve": [
      "Client Kit 4.x to 5.0; local token storage only",
      "Custom tokenStore users unaffected",
      "Export before upgrade",
      "persistTokens removed; replacement tokenStore: new FileTokenStore(path); same path",
      "Test session token survives restart; keep export until check passes",
      "5.0 writes incompatible with 4.x; rollback requires export restore"
    ],
    "kind": "illustrative",
    "omitted": [
      "The guide introduction and repeated references to the upgrade and database."
    ]
  }
}