CLI Deprecation Notice Drafting Prompt

This prompt is designed for product managers, CLI maintainers, and developer relations engineers who need to draft a formal deprecation notice for a flag, subcommand, or behavioral change in a command-line tool. The core job-to-be-done is transforming a raw engineering decision—'we are removing --old-flag in v3'—into a structured, user-facing communication artifact that includes a clear timeline, migration commands, and an impact assessment. It is not a general-purpose announcement writer; it is a precision tool for technical surfaces where an incorrect or vague notice can break downstream CI/CD pipelines and automation scripts.

Use this prompt when you have a specific, scoped deprecation target and know the replacement path. The ideal user provides concrete context: the exact deprecated surface, the version where deprecation begins, the version where removal occurs, and the verified replacement command or behavior. The prompt requires a [DEPRECATION_TARGET] (e.g., --old-auth), a [REPLACEMENT_GUIDANCE] (e.g., Use --new-auth with an OAuth token), and a [VERSION_TIMELINE] (e.g., Deprecated in v2.5, removed in v3.0). The harness should validate that the replacement command actually executes successfully against the current CLI build before the notice is published, preventing the most common failure mode: recommending a migration path that is already broken.

Do not use this prompt for marketing announcements, blog posts, or high-level product sunsetting emails. It is also unsuitable when the replacement path is unknown, the timeline is speculative, or the deprecation affects a broad behavioral change without a direct command mapping. In those cases, a human must first resolve the ambiguity. The output is a structured notice, not a legal document; for regulated industries, always route the final draft through legal and product review. After generating the notice, immediately run the [REPLACEMENT_GUIDANCE] commands in a CI environment to confirm they exit with code 0 and produce the expected output, then attach the validation log to the notice before publication.

This template is the core instruction set you will send to the model. It is designed to be copied directly into your prompt management system, test harness, or application code. Every variable is enclosed in square brackets, such as [DEPRECATED_SURFACE], and must be replaced with concrete values before execution. The prompt enforces a strict output structure, requires a migration command that can be validated, and asks the model to assess user impact rather than just announcing a change.

textCopy
You are a technical product manager and CLI maintainer drafting a deprecation notice for a command-line tool. Your goal is to produce a clear, actionable notice that minimizes user surprise and provides a verified migration path.

## Inputs
- Deprecated Surface: [DEPRECATED_SURFACE]
- CLI Tool Name: [TOOL_NAME]
- Target Removal Version: [REMOVAL_VERSION]
- Current Version: [CURRENT_VERSION]
- Replacement Surface: [REPLACEMENT_SURFACE]
- Migration Command Example: [MIGRATION_COMMAND]
- Additional Context: [ADDITIONAL_CONTEXT]

## Constraints
- Do not invent dates, versions, or commands not provided in the inputs.
- If the replacement surface does not exist or the migration command is unverified, state that clearly and recommend human verification.
- Use a professional, helpful tone. Do not apologize excessively.
- The notice must be self-contained and suitable for a changelog, terminal warning, or documentation page.

## Output Schema
Return a single JSON object with the following keys:
- "headline": A one-sentence summary of the deprecation.
- "affected_surfaces": An array of strings listing every flag, subcommand, or behavior being deprecated.
- "timeline": An object with keys "deprecated_in", "removed_in", and "recommended_action_by".
- "replacement_guidance": A string explaining the new way to achieve the same outcome.
- "migration_command": The exact, copy-pasteable command users should run to migrate.
- "impact_assessment": A string describing who is affected, how many calls or workflows are likely impacted, and the severity.
- "human_review_required": A boolean set to true if the migration command has not been verified against the current CLI version.

## Examples
Input: Deprecated Surface: `--old-format csv`, Tool: `data-cli`, Removal Version: `v2.0.0`, Replacement: `--format csv --engine v2`
Output: {"headline": "The `--old-format` flag is deprecated and will be removed in data-cli v2.0.0", ...}

Now, draft the deprecation notice for the provided inputs.

To adapt this template, replace every square-bracket placeholder with data from your release tracking system or CLI introspection harness. The [MIGRATION_COMMAND] field is the most critical: it must be a command that your test suite has executed successfully against the replacement surface. If you cannot provide a verified command, set the input to "UNVERIFIED" and the model will flag human_review_required as true. For production use, store this prompt in a version-controlled prompt library and pair it with a post-generation validator that checks the output JSON schema, confirms the migration command is present, and escalates any notice where human_review_required is true to a review queue before publication.

This prompt is not a standalone text generator; it is a component in a deprecation communication pipeline. The harness must enforce that every generated notice is grounded in a concrete, machine-readable change manifest—such as a JSON list of deprecated flags, subcommands, or behaviors extracted directly from the CLI's source code or changelog. The prompt's [DEPRECATED_SURFACES] placeholder should be populated programmatically from this manifest, not typed by hand. This prevents the most common failure mode: a beautifully written notice that omits a deprecated flag because the author forgot to list it.

The implementation harness should run three validation gates before any notice reaches a human reviewer. First, a coverage check compares the set of deprecated surfaces mentioned in the generated notice against the input manifest and flags any missing items. Second, a command execution test extracts every --replacement-command or migration snippet from the notice and runs it in a sandboxed environment against the target CLI version to verify it exits successfully and produces the expected output. Third, a timeline consistency check parses all dates in the notice and confirms they are logically ordered (warning date < deprecation date < removal date) and not in the past. If any gate fails, the system should route the notice back for regeneration with the specific failure details injected into the [CONSTRAINTS] field.

Human review remains essential because deprecation notices carry product and customer relationship risk. The harness should present the validated notice alongside a diff of the change manifest, the results of the three automated gates, and a checklist for the reviewer: confirm the tone matches the project's communication policy, verify the migration timeline accounts for customer upgrade cycles, and approve the escalation contact information. Only after explicit approval should the notice be published to changelogs, documentation sites, or direct customer communications. Do not automate publication without this review step, as a premature or incorrectly scoped deprecation notice can erode trust with your most invested users.