Graceful Deprecation Language Prompt Template

This prompt is designed for technical writers, API product managers, and developer relations engineers who need to generate deprecation communication templates that match the urgency of a specific phase in a sunset lifecycle. The core job-to-be-done is translating a confirmed deprecation decision, a defined timeline, and a known replacement path into three distinct message variants: an advisory notice, a standard warning, and a final reminder. The output is not a single message but a set of templates that can be calibrated for progressive urgency, ensuring that developer communications escalate appropriately without causing unnecessary alarm or eroding trust.

Use this prompt only when three preconditions are met: the deprecation decision is finalized and approved by the relevant governance body, the replacement API, SDK method, or feature is stable and publicly documented, and a concrete timeline with specific dates (announcement, brownout, end-of-life) has been established. The prompt requires structured inputs including [DEPRECATED_SURFACE], [REPLACEMENT_PATH], [TIMELINE_MILESTONES], [IMPACT_ASSESSMENT], and [ESCALATION_CONTACTS]. Do not use this prompt before the deprecation decision is finalized, when the replacement is still in an unstable or private beta state, or when the timeline is speculative. Using it prematurely will produce language that over-promises on migration paths or under-communicates risk, damaging developer confidence.

The output requires mandatory human review before publication. A technical writer or DevRel lead must verify date accuracy against the official deprecation schedule, calibrate the tone for the specific audience segment (e.g., free-tier vs. enterprise consumers), and confirm that escalation contacts and support links are current. For high-severity deprecations that affect paying customers or regulated workloads, legal and compliance review is also required. After adapting the generated templates, run them through the Deprecation Communication Review Rubric Prompt to score completeness, accuracy, and tone before any channel distribution.

This template produces deprecation language for warnings, notices, and final reminders. It accepts the deprecation context, target audience, urgency level, and tone constraints, then outputs a structured message with subject line, body, call-to-action, and migration guidance. Copy the template into your prompt layer, replace the square-bracket placeholders with actual values, and run it against your deprecation context.

textCopy
You are a technical communications specialist drafting deprecation messages for developer-facing APIs, SDK methods, or features. Your goal is to communicate urgency clearly without causing unnecessary alarm. Maintain developer trust by being precise about dates, replacement paths, and support windows.

Generate a deprecation message using the following inputs:

[DEPRECATION_CONTEXT]
- What is being deprecated: [DEPRECATED_ITEM]
- Replacement or alternative: [REPLACEMENT_PATH]
- Deprecation stage: [STAGE]  // Options: "advance-notice", "active-warning", "final-reminder", "post-shutdown"
- Effective date of this stage: [EFFECTIVE_DATE]
- Shutdown or removal date: [SHUTDOWN_DATE]
- Support end date: [SUPPORT_END_DATE]
- Impact summary: [IMPACT_DESCRIPTION]

[AUDIENCE]
- Recipient role: [AUDIENCE_ROLE]  // e.g., "API consumers", "SDK integrators", "internal service owners"
- Technical proficiency: [TECHNICAL_LEVEL]  // Options: "expert", "intermediate", "mixed"
- Existing relationship: [RELATIONSHIP]  // Options: "active-customer", "inactive-customer", "internal-team", "partner"

[TONE_CONSTRAINTS]
- Urgency calibration: [URGENCY]  // Options: "low" (advisory), "medium" (action required), "high" (imminent shutdown)
- Empathy level: [EMPATHY]  // Options: "standard", "elevated" (for high-impact changes)
- Brand voice notes: [BRAND_VOICE_NOTES]

[OUTPUT_SCHEMA]
Return a JSON object with these fields:
{
  "subject_line": "string",
  "body": "string (markdown allowed)",
  "call_to_action": "string",
  "migration_steps": ["string"],
  "contact_information": "string",
  "tone_assessment": {
    "urgency_score": "number (1-5)",
    "alarm_risk": "string (low/medium/high)",
    "clarity_score": "number (1-5)"
  }
}

[CONSTRAINTS]
- Include exact dates in ISO 8601 format (YYYY-MM-DD) wherever dates appear.
- Never invent replacement features or timelines not present in [DEPRECATION_CONTEXT].
- If [STAGE] is "final-reminder" or "post-shutdown", the call_to_action must not imply the deprecated item is still available.
- For [URGENCY]="high", include an escalation contact.
- Keep the body under 300 words unless [STAGE]="advance-notice" with complex migration steps.
- Do not use alarming language such as "URGENT," "CRITICAL," or "IMMEDIATE ACTION REQUIRED" in all-caps unless [URGENCY]="high" and [STAGE]="final-reminder".
- If [AUDIENCE_ROLE] includes partners, add a partner-support contact distinct from general support.

To adapt this template, replace each square-bracket placeholder with concrete values from your deprecation plan. The [STAGE] field controls the message's posture: advance notices emphasize planning time, active warnings emphasize action deadlines, final reminders emphasize cutoff dates, and post-shutdown messages confirm removal and point to alternatives. The tone assessment fields in the output help you validate that the generated message matches the intended urgency without triggering unnecessary alarm. Before sending any generated message to production, run the output through your deprecation communication review rubric and require human approval for [URGENCY]="high" or any message targeting external paying customers.

This prompt is designed to be called programmatically as part of a documentation generation or review pipeline, not as a one-off chat interaction. The primary integration points are a content management system (CMS), a docs-as-code CI/CD pipeline, or an internal communications tool that drafts deprecation notices for review. The application layer is responsible for assembling the required inputs—[DEPRECATION_DETAILS], [AUDIENCE_PROFILE], [URGENCY_LEVEL], and [BRAND_VOICE_GUIDELINES]—before constructing the final prompt instance. The model's raw output should never be published directly; it must pass through a structured validation and human approval stage.

Wire the prompt into your application with a strict pre-generation and post-generation harness. Before calling the model, validate that all required placeholders are populated and that the [URGENCY_LEVEL] value is one of the allowed enums: standard, elevated, or critical. After receiving the model's response, run a schema validator to confirm the output is valid JSON with the required keys: subject_line, message_body, urgency_justification, and tone_analysis. If the JSON is malformed, implement a single retry with a repair prompt that includes the raw output and the schema error. For high-risk critical deprecations, the system should automatically create a ticket in a human review queue and block publication until an authorized reviewer approves the message_body and urgency_justification. Log the full prompt, response, validation result, and reviewer decision for auditability.

For model choice, a capable mid-tier model like claude-3.5-sonnet or gpt-4o is sufficient for generating the structured draft, as the task requires tone calibration and schema adherence rather than deep reasoning. If your documentation platform already uses Retrieval-Augmented Generation (RAG) for style guide enforcement, you can inject your [BRAND_VOICE_GUIDELINES] as the top-ranked retrieval chunk. Do not use this prompt to generate the final legal disclaimer; that text should be sourced from a pre-approved legal fragment library and inserted into the message_body by the application layer after generation. The next step is to build a regression test suite using the eval criteria from the 'Testing & Eval Criteria' section to catch tone drift and schema violations before they reach the human review stage.