Deprecation Handler

This skill helps safely identify, assess, and migrate deprecated code to modern alternatives. It ensures systematic handling of deprecated APIs, types, functions, and modules.

When to Use

Invoke this skill when:

• Encountering deprecation warnings in compiler/linter output
• Modifying files containing deprecated code
• Upgrading dependencies that introduce breaking changes
• Reviewing code that uses legacy APIs or patterns
• Planning refactoring work on older codebases
• Investigating build warnings or IDE strikethrough indicators

Workflow

Step 1: Detect Deprecations

Automated Detection:

# TypeScript compiler warnings
npx tsc --noEmit

# Dependency audit
npm outdated
yarn outdated

# Check for deprecated packages
npm deprecate-check

Manual Detection:

• Review IDE warnings (strikethrough text, warning indicators)
• Check console output in development environment
• Examine framework migration guides
• Review official changelogs for upgraded versions

Output: Create a catalog of all detected deprecations with:

• Location (file path, line number)
• Deprecated API/function/type name
• Deprecation message/reason
• Recommended replacement (if provided)

Step 2: Assess Impact

Classify by Priority:

• Immediate: Security vulnerabilities, breaking changes in next version, performance-critical
• High: Simple replacements, touching file anyway, direct alternatives available
• Medium: Requires refactoring, architectural changes, distant sunset timeline
• Low: Monitor only, optional optimizations, style-only changes

Analyze Scope:

• Count total usages across codebase
• Identify affected modules/components
• Determine dependencies and coupling
• Estimate migration effort (hours/days)

Risk Assessment:

• Breaking change potential
• Test coverage of affected code
• API stability of replacement
• Migration path complexity

Step 3: Plan Migration

For Immediate/High Priority:

1. Identify direct replacement from deprecation message
2. Check official migration guide
3. Verify replacement is stable and well-documented
4. Plan incremental changes (file-by-file or module-by-module)
5. Ensure test coverage exists or add tests

For Medium/Low Priority:

1. Document deprecation with inline comments
2. Create task/issue for future work
3. Note blockers preventing immediate fix
4. Link to migration guide or documentation
5. Set review timeline based on sunset date

Output: Migration plan with:

• Prioritized list of changes
• File-by-file or module-by-module strategy
• Required testing approach
• Rollback plan if needed

Step 4: Execute Replacement

Safe Migration Pattern:

// 1. Add new implementation alongside old
const newImplementation = modernApi.newMethod(params);

// 2. Validate equivalence in tests
expect(newImplementation).toEqual(oldImplementation);

// 3. Replace usage
// const result = legacyApi.deprecatedMethod(params); // DEPRECATED
const result = modernApi.newMethod(params);

// 4. Remove old code after validation

Incremental Approach:

• Fix one file/module at a time
• Run tests after each change
• Commit working changes incrementally
• Keep related changes together
• Document non-obvious replacements

For Simple Cases (same file):

// Before
import { deprecatedFunc } from 'old-package';
deprecatedFunc(arg);

// After
import { newFunc } from 'new-package';
newFunc(arg);

For Complex Cases (separate commit/PR):

1. Create migration branch
2. Update implementation with new API
3. Add comprehensive tests
4. Document breaking changes
5. Review and merge separately

Step 5: Validate Changes

Automated Validation:

# Type checking
npx tsc --noEmit

# Linting (should show fewer deprecation warnings)
npx eslint . --ext .ts,.tsx,.js,.jsx

# Run test suite
npm test
yarn test

# Build verification
npm run build
yarn build

Manual Validation:

• Review IDE for remaining deprecation warnings
• Check console for runtime warnings
• Verify functionality in development environment
• Test edge cases and error conditions
• Review diff for unintended changes

Regression Prevention:

• Ensure all tests pass
• Verify no new TypeScript errors
• Check that linting warnings decreased
• Confirm build succeeds
• Test affected features manually

Common Migration Patterns

See resources/migration-patterns.md for detailed examples of:

• React lifecycle to hooks
• Class components to functional components
• Deprecated npm packages to modern alternatives
• Legacy API patterns to current best practices
• Framework-specific migration guides

Documentation Requirements

For Unfixed Deprecations

When deprecations cannot be immediately fixed:

/**
 * TODO: Migrate to newApi.modernMethod() when v3 migration is complete
 *
 * Current usage of deprecatedMethod() due to:
 * - Dependency on legacy authentication system
 * - Breaking

...