speckit-workflows-deprecate

name	speckit-workflows-deprecate
description	Initiate a feature deprecation workflow with phased sunset process (warnings -> disabled -> removed).
compatibility	Requires spec-kit project structure with .specify/ directory
metadata	{"author":"github-spec-kit","source":"workflows:commands/deprecate.md"}

The user input to you can be provided directly by the agent or as a command argument - you MUST consider it before proceeding with the prompt (if not empty).

User input:

$ARGUMENTS

The text the user typed after /speckit.workflows.deprecate (or /speckit.deprecate) in the triggering message can be:

• /speckit.workflows.deprecate <feature_number> "reason" - Direct with feature number
• /speckit.workflows.deprecate "reason" - Interactive (will prompt for feature selection)

For example: /speckit.workflows.deprecate 014 "low usage and high maintenance burden" or /speckit.workflows.deprecate "low usage". Assume you always have it available even if $ARGUMENTS appears literally below.

DEPRECATION WORKFLOW - PHASED SUNSET

Given that input, do this:

1. Parse $ARGUMENTS to check if feature number is provided

   • If starts with 3 digits (e.g., "014 low usage"), extract feature number and reason
   • If no leading digits (e.g., "low usage"), treat as reason-only (interactive mode)

2. If interactive mode (no feature number provided): a. Run .specify/extensions/workflows/scripts/bash/create-deprecate.sh --list-features "$REASON" to get list of features b. Parse the JSON output which contains: {"mode":"list","reason":"...","features":[...]} c. Present the features list to the user in a clear, numbered format:

   Which feature do you want to deprecate?
   
   1. 001 - ability-for-new
   2. 002 - ability-for-users
   3. 014 - edit-profile-form
   ...
   
   Type the feature number (e.g., 014) or respond with the line number (e.g., 3).
   

   d. Wait for user response with their selection e. Extract the feature number from their response (handle both "014" and "3" formats) f. Continue to step 3 with the selected feature number

3. Normal workflow (feature number now available): Run the script .specify/extensions/workflows/scripts/bash/create-deprecate.sh --json "$FEATURE_NUM" "$REASON" from repo root and parse its JSON output for DEPRECATE_ID, BRANCH_NAME, DEPRECATION_FILE, TASKS_FILE, DEPENDENCIES_FILE, FEATURE_NUM, FEATURE_NAME, and REASON. All file paths must be absolute. IMPORTANT You must only ever run this script once per feature selection. The JSON is provided in the terminal as output - always refer to it to get the actual content you're looking for.

4. Load .specify/extensions/workflows/templates/deprecate/deprecation-template.md to understand the 3-phase approach (Warnings -> Disabled -> Removed).

5. Read the DEPENDENCIES_FILE that was auto-generated by the scan-dependencies.sh script. This contains critical information about what code depends on the feature being deprecated.

6. Write a comprehensive deprecation plan to DEPRECATION_FILE using the template structure:

   • Fill in feature name and original feature reference
   • Document the rationale (use the provided reason)
   • Assess affected users and usage data (if available from analytics)
   • Review the dependency scan results and document all dependencies
   • Define migration path to alternative solution
   • Set realistic timeline for 3 phases (typically 3-6 months total)
   • Plan communication strategy for each phase
   • Document rollback plans for each phase
   • Assess risks (user impact, technical debt, business impact)

7. Report completion with Next Steps:

Deprecation workflow initialized

**Deprecation ID**: [DEPRECATE_ID]
**Feature**: specs/[FEATURE_NAME] (Feature [FEATURE_NUM])
**Reason**: [REASON]
**Branch**: [BRANCH_NAME]
**Deprecation Plan**: [DEPRECATION_FILE]
**Dependencies Scan**: [DEPENDENCIES_FILE]

**Next Steps:**
1. Review deprecation plan and dependency scan
2. Refine timeline for 3-phase sunset (typically 3-6 months)
3. Get stakeholder approvals (Product, Engineering, Support)
4. Run `/speckit.plan` to create detailed phase execution plans
5. Run `/speckit.tasks` to break down each phase into tasks
6. Run `/speckit.implement` to execute Phase 1 (warnings)

**Reminder**: 3-phase approach ensures smooth user migration

Important Notes:

• Deprecation is a multi-month process - not a quick fix
• Each phase requires careful planning and communication
• Users need time to migrate - rushing causes churn
• The dependency scan helps identify code that will break when feature is removed
• This workflow emphasizes user communication as much as technical removal
• Always provide a migration path to an alternative solution
• Get stakeholder sign-off before starting (Product, Engineering, Support)

Interactive Mode Usage Examples:

• User: /speckit.workflows.deprecate "low usage" -> Shows feature list -> User selects -> Creates deprecation plan
• User: /speckit.workflows.deprecate 014 "low usage" -> Directly creates deprecation plan for feature 014