Migration Guide Writer Skill

Purpose

Create comprehensive migration guides for moving from old systems/APIs to new ones. Follows the Diátaxis How-To pattern for problem-oriented documentation. Verifies all APIs in both old and new systems before documenting, with zero tolerance for fabrication.

Diátaxis Framework: How-To Guide

How-To Type Characteristics:

• Problem-oriented - Focused on specific migration goal
• Assumes knowledge - Not teaching from zero (that's tutorials)
• Series of steps - Path from old to new
• Multiple approaches - May show different migration strategies
• Real-world scenarios - Production migration patterns
• Troubleshooting - Common issues and solutions

What NOT to Include:

• ❌ Tutorials (learning from zero) - Use tutorial-writer skill
• ❌ Complete API reference - Link to api-doc-writer docs
• ❌ Deep explanations of WHY - Link to explanation docs
• ❌ Marketing comparisons - Technical facts only

Critical Rules (Zero Tolerance)

P0 - CRITICAL Violations (Must Fix)

1. Fabricated Old APIs - Old methods that never existed
2. Fabricated New APIs - New methods that don't exist in source
3. Wrong Signatures - Before/After code with incorrect APIs
4. Unverified Performance Claims - "10x faster" without benchmarks
5. Invalid Migration Code - Code that won't compile

P1 - HIGH Violations (Should Fix)

6. Missing Troubleshooting - No guidance for common errors
7. Incomplete Breaking Changes - Not documenting all changes
8. Unverified Timing Claims - Fabricated latency numbers

P2 - MEDIUM Violations

9. Marketing Language - Buzzwords instead of technical facts
10. Missing Prerequisites - Not stating version requirements

Step-by-Step Workflow

Quick 5-Phase Process

1. Systems Analysis - Verify old/new APIs, create mapping checklist, search for benchmarks
2. Pattern Identification - Identify migration patterns (CRUD, auth, config, errors, async)
3. Documentation - Write structured migration guide with Before/After examples
4. Troubleshooting - Anticipate common errors (compilation, runtime, logical)
5. Verification - Verify all code against source, remove unverified claims

For detailed step-by-step instructions with examples, templates, and verification checklists, see references/WORKFLOW-STEPS.md.

Integration with Other Skills

Works With:

• api-doc-writer - Link to new system API reference
• tutorial-writer - Link to getting started with new system
• api-documentation-verify - Verify migration guide accuracy

Invokes:

• None (standalone skill)

Invoked By:

• User (manual invocation)
• After major version releases
• When deprecating old systems

Output Format

Primary Output: Markdown file with structured migration guide

File Location:

• docs/migrations/[old]-to-[new].md
• MIGRATION.md in project root
• docs/how-to/migrate-from-[old].md

Common Pitfalls to Avoid

1. Unverified Performance Claims

❌ BAD - No benchmark evidence
The new system is 10x faster than the old system

✅ GOOD - Factual architectural statement
The new system eliminates network overhead by using in-process calls
[If benchmarks exist]: See benchmarks/comparison.bench.ts for measurements

2. Fabricated New APIs

❌ BAD - API doesn't exist
// After (New System)
await newSystem.easyMigrate(oldConfig) // This method was never implemented!

✅ GOOD - Real API from source
// After (New System)
const adapter = new ConfigAdapter(oldConfig)
await newSystem.initialize(adapter.transform())

3. Incomplete Breaking Changes

❌ BAD - Missing changes
Major changes: Method renamed

✅ GOOD - Complete list
Breaking Changes:

1. CreateTask() renamed to Create()
2. Create() now requires ctx parameter
3. TaskParams.Owner changed from string to UserId type
4. UpdateTask() removed - use Patch() instead
5. Error type changed from string to TaskError

4. Missing Troubleshooting

❌ BAD - No troubleshooting section
[Guide ends after migration patterns]

✅ GOOD - Comprehensive troubleshooting

## Troubleshooting

[Multiple common issues with solutions]

Time Estimates

Small Migration (< 5 API changes): 45 minutes - 1.5 hours Medium Migration (5-15 API changes): 1.5 - 3 hours Large Migration (15+ changes): 3 - 6 hours System Replacement: 4 - 8 hours

Example Usage

# Manual invocation
/skill migration-guide-writer

# User request
User: "How do I migrate from the old TaskService to the new one?"
Assistant: "I'll use migration-guide-writer to create a comprehensive migration guide"

Success Criteria

Migration guide is complete when:

• ✅ All new system APIs verified against source
• ✅ Before/After examples for all common patterns
• ✅ All breaking changes documented
• ✅ Troubleshooting section included
• ✅ No unverified performance claims
• ✅ No fabricated APIs
• ✅ Migration checklist provided
• ✅ Prerequisites clearly stated
• ✅ Configuration migration documented
• ✅ No marketing language

References

• Diátaxis Framework: https://diataxis.fr/how-to-guides/
• Technical Documentation Expert Agent
• API Documentation Writer skill (for referencing APIs)

Related Agent

For comprehensive documentation guidance that coordinates this and other documentation skills, use the documentation-coordinator agent.