12 KiB
12 KiB
description
| description |
|---|
| Phased feature sunset workflow with migration guidance |
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)