/deprecate | specswarm | ClaudePluginHub

User Input

$ARGUMENTS

You MUST consider the user input before proceeding (if not empty).

Goal

Execute phased deprecation workflow to safely sunset features while providing migration guidance to users.

Key Principles:

Phased Approach: Announce → Migrate → Remove
Migration Guidance: Provide clear alternatives
User Support: Help users migrate
Track Adoption: Monitor migration progress
Safe Removal: Only remove when migration complete

Phases: Announce deprecation, user migration support, feature removal

Coverage: Addresses ~5% of development work (feature evolution)

Smart Integration

SPECSWARM_INSTALLED=$(claude plugin list | grep -q "specswarm" && echo "true" || echo "false")
SPECTEST_INSTALLED=$(claude plugin list | grep -q "spectest" && echo "true" || echo "false")

if [ "$SPECTEST_INSTALLED" = "true" ]; then
  ENABLE_HOOKS=true
  ENABLE_METRICS=true
fi

Execution Steps

1. Discover Deprecation Context

REPO_ROOT=$(git rev-parse --show-toplevel 2>/dev/null || pwd)
CURRENT_BRANCH=$(git rev-parse --abbrev-ref HEAD 2>/dev/null)
DEPRECATE_NUM=$(echo "$CURRENT_BRANCH" | grep -oE 'deprecate/([0-9]{3})' | grep -oE '[0-9]{3}')

if [ -z "$DEPRECATE_NUM" ]; then
  echo "📉 Deprecate Workflow"
  echo "Provide deprecation number:"
  read -p "Deprecation number: " DEPRECATE_NUM
  DEPRECATE_NUM=$(printf "%03d" $DEPRECATE_NUM)
fi

# Source features location helper
SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
PLUGIN_DIR="$(dirname "$SCRIPT_DIR")"
source "$PLUGIN_DIR/lib/features-location.sh"

# Initialize features directory
ensure_features_dir "$REPO_ROOT"

FEATURE_DIR="${FEATURES_DIR}/${DEPRECATE_NUM}-deprecate"
mkdir -p "$FEATURE_DIR"

DEPRECATE_SPEC="${FEATURE_DIR}/deprecate.md"
MIGRATION_GUIDE="${FEATURE_DIR}/migration-guide.md"
TASKS_FILE="${FEATURE_DIR}/tasks.md"

2. Identify Feature to Deprecate

📉 Feature Deprecation

Which feature are you deprecating?
[User input or scan codebase]

Feature to deprecate: [name]
Reason for deprecation: [reason]
Alternative/replacement: [what users should use instead]

3. Create Deprecation Specification

# Deprecation ${DEPRECATE_NUM}: [Feature Name]

**Status**: Active
**Created**: YYYY-MM-DD
**Feature**: [Feature to deprecate]
**Replacement**: [Alternative feature/approach]

---

## Deprecation Rationale

**Why Deprecating**:
- Reason 1
- Reason 2
- Reason 3

**Timeline Decision**: [Why now?]

---

## Current Usage Analysis

**Users Affected**: [Estimated N users/systems]
**Usage Patterns**: [How is it currently used?]

**Dependencies**:
| Dependent System | Usage Level | Migration Complexity |
|------------------|-------------|----------------------|
| [System 1] | [High/Med/Low] | [High/Med/Low] |

---

## Replacement Strategy

**Recommended Alternative**: [Feature/approach]

**Why Better**:
- Benefit 1
- Benefit 2

**Migration Effort**: [Low/Medium/High]
**Migration Time Estimate**: [timeframe per user]

---

## Deprecation Timeline

### Phase 1: Announcement (Month 1)
**Duration**: [timeframe]
**Activities**:
- [ ] Announce deprecation publicly
- [ ] Add deprecation warnings to feature
- [ ] Publish migration guide
- [ ] Email affected users
- [ ] Update documentation

**Deliverables**:
- Deprecation announcement
- Migration guide
- Updated docs

---

### Phase 2: Migration Support (Months 2-3)
**Duration**: [timeframe]
**Activities**:
- [ ] Monitor adoption of alternative
- [ ] Provide migration support to users
- [ ] Track usage of deprecated feature
- [ ] Address migration blockers
- [ ] Send migration reminders

**Success Criteria**:
- ≥80% of users migrated to alternative
- No critical dependencies remaining

---

### Phase 3: Removal (Month 4+)
**Duration**: [timeframe]
**Activities**:
- [ ] Final migration reminder (2 weeks notice)
- [ ] Disable feature in production
- [ ] Remove code
- [ ] Cleanup tests and documentation
- [ ] Archive feature artifacts

**Prerequisites**:
- ≥90% user migration
- All critical dependencies resolved
- Stakeholder approval

---

## Migration Blockers

**Known Blockers**:
| Blocker | Impact | Resolution Plan |
|---------|--------|-----------------|
| [Blocker 1] | [High/Med/Low] | [How to resolve] |

---

## Communication Plan

**Channels**:
- [ ] Blog post / changelog
- [ ] Email to affected users
- [ ] In-app deprecation warning
- [ ] Documentation update
- [ ] Support ticket template

**Messaging**:
- Clear deprecation timeline
- Migration guide link
- Support resources
- Benefits of alternative

---

## Rollback Plan

**If Migration Fails**:
- Extend timeline
- Provide additional support resources
- Reconsider deprecation if alternative insufficient

---

## Success Metrics

| Metric | Target | Current |
|--------|--------|---------|
| User Migration Rate | ≥90% | [%] |
| Alternative Adoption | ≥80% | [%] |
| Support Tickets | <10 | [N] |
| Migration Blockers | 0 | [N] |

---

## Metadata

**Workflow**: Deprecate (Phased Sunset)
**Created By**: SpecLab Plugin v1.0.0

Write to $DEPRECATE_SPEC.

4. Create Migration Guide

# Migration Guide: Deprecation ${DEPRECATE_NUM}

**Feature Deprecated**: [Feature name]
**Recommended Alternative**: [Alternative]
**Migration Deadline**: [Date]

---

## Why This Change?

[Brief explanation of deprecation rationale]

**Benefits of Migration**:
- Benefit 1
- Benefit 2

---

## Migration Steps

### Step 1: [Action]
**What**: [Description]

**Before** (deprecated):

[Code example using old feature]


**After** (recommended):

[Code example using alternative]


### Step 2: [Action]
[Repeat pattern for each migration step]

---

## Migration Checklist

- [ ] Update code to use alternative
- [ ] Update tests
- [ ] Update documentation
- [ ] Test in development
- [ ] Deploy to production
- [ ] Verify functionality
- [ ] Remove deprecated feature usage

---

## Common Migration Scenarios

### Scenario 1: [Use Case]
**Old Approach**:

[Code]


**New Approach**:

[Code]


[Repeat for common scenarios]

---

## Troubleshooting

### Issue 1: [Common Problem]
**Symptom**: [What users see]
**Solution**: [How to fix]

[Repeat for common issues]

---

## Support Resources

- Migration guide: [link]
- API documentation: [link]
- Support channel: [link]
- Example migration: [link to example code]

**Need Help?**
- Email: [support email]
- Slack: [support channel]
- Office hours: [time]

---

## Timeline

- **Now**: Feature deprecated, warnings active
- **[Date]**: Migration support ends
- **[Date]**: Feature removed from production

**Don't wait! Migrate today.**

Write to $MIGRATION_GUIDE.

5. Generate Tasks

# Tasks: Deprecation ${DEPRECATE_NUM}

**Workflow**: Deprecate (Phased Sunset)

---

## Phase 1: Announcement Tasks

### T001: Add Deprecation Warnings
**Description**: Add warnings to deprecated feature code
**Files**: [list]
**Warning Message**: "This feature is deprecated. Migrate to [alternative]. See [migration guide link]."

### T002: [P] Publish Migration Guide
**Description**: Publish migration guide
**Output**: ${MIGRATION_GUIDE}
**Parallel**: [P]

### T003: [P] Update Documentation
**Description**: Mark feature as deprecated in docs
**Files**: [doc files]
**Parallel**: [P]

### T004: [P] Announce Deprecation
**Description**: Communicate deprecation via all channels
**Channels**: Blog, email, in-app
**Parallel**: [P]

---

## Phase 2: Migration Support Tasks

### T005: Monitor Adoption
**Description**: Track usage of deprecated vs alternative
**Metrics**: [usage metrics]
**Frequency**: Weekly
**Duration**: [Phase 2 duration]

### T006: Provide User Support
**Description**: Help users migrate
**Activities**: Answer questions, resolve blockers
**Duration**: [Phase 2 duration]

### T007: Send Migration Reminders
**Description**: Remind users to migrate
**Schedule**: [reminder schedule]
**Content**: Progress update, deadline reminder

---

## Phase 3: Removal Tasks

### T008: Final Migration Check
**Description**: Verify ≥90% user migration
**Validation**: Usage metrics, stakeholder approval

### T009: Disable Feature
**Description**: Turn off deprecated feature in production
**Rollback Plan**: [how to re-enable if needed]

### T010: Remove Code
**Description**: Delete deprecated feature code
**Files**: [list all files to remove]
**Validation**: Tests still pass

### T011: [P] Cleanup Tests
**Description**: Remove tests for deprecated feature
**Files**: [test files]
**Parallel**: [P]

### T012: [P] Cleanup Documentation
**Description**: Remove deprecated feature from docs
**Files**: [doc files]
**Parallel**: [P]

### T013: Archive Artifacts
**Description**: Archive feature artifacts for historical reference
**Location**: [archive location]

---

## Summary

**Total Tasks**: 13
**Phase 1 (Announce)**: T001-T004 (4 tasks, [N] parallel)
**Phase 2 (Migrate)**: T005-T007 (3 tasks, ongoing)
**Phase 3 (Remove)**: T008-T013 (6 tasks, [N] parallel)

**Total Timeline**: [estimated timeline]

**Success Criteria**:
- ✅ Deprecation announced to all users
- ✅ Migration guide published
- ✅ ≥90% users migrated
- ✅ Feature removed safely
- ✅ Documentation updated

Write to $TASKS_FILE.

6. Execute Phased Deprecation

Execute across three phases:

📉 Executing Deprecation Workflow

Phase 1: Announcement (Month 1)
T001: Add Deprecation Warnings
  ✓ Warnings added to code

T002-T004: [Parallel] Publish Migration Guide, Update Docs, Announce
  ⚡ Executing 3 tasks in parallel...
  ✓ Migration guide published
  ✓ Documentation updated
  ✓ Deprecation announced

Phase 2: Migration Support (Months 2-3)
T005: Monitor Adoption
  Week 1: 15% migrated
  Week 2: 32% migrated
  Week 4: 58% migrated
  Week 6: 78% migrated
  Week 8: 91% migrated ✅

T006: Provide User Support
  ✓ 12 support tickets resolved
  ✓ 3 migration blockers fixed

T007: Send Migration Reminders
  ✓ Weekly reminders sent

Phase 3: Removal (Month 4)
T008: Final Migration Check
  ✓ 91% users migrated
  ✓ Stakeholder approval received

T009: Disable Feature
  ✓ Feature disabled in production
  ✓ No issues reported

T010-T012: [Parallel] Remove Code, Cleanup Tests, Cleanup Docs
  ⚡ Executing 3 tasks in parallel...
  ✓ All cleanup tasks complete

T013: Archive Artifacts
  ✓ Artifacts archived

Final Output

✅ Deprecation Workflow Complete - Deprecation ${DEPRECATE_NUM}

📊 Deprecation Results:
- Users migrated: 91% ✅
- Alternative adopted: 87% ✅
- Support tickets: 12 (all resolved) ✅
- Timeline: Completed on schedule ✅

📋 Artifacts:
- ${DEPRECATE_SPEC}
- ${MIGRATION_GUIDE}
- ${TASKS_FILE}

⏱️  Total Timeline: [duration]

✅ Feature Safely Removed:
- Code deleted and archived
- Documentation updated
- Users successfully migrated

📈 Next Steps:
- Monitor alternative feature adoption
- Archive learnings for future deprecations

Operating Principles

Phased Approach: Announce → Migrate → Remove
User-Centric: Help users migrate successfully
Communication: Over-communicate timeline and alternatives
Track Progress: Monitor migration adoption
Safe Removal: Only remove when migration complete

Success Criteria

✅ Deprecation announced to all affected users ✅ Migration guide published and accessible ✅ ≥90% user migration achieved ✅ Migration blockers resolved ✅ Feature removed safely ✅ Documentation and code cleanup complete ✅ Artifacts archived

Workflow Coverage: Addresses ~5% of development work (feature evolution)