---
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