Deprecation Timeline Communication Prompt Template

This prompt is designed for release managers, API product managers, and platform governance teams who need to produce a structured, multi-phase deprecation timeline from a set of raw inputs. It takes a deprecated surface identifier, target dates, replacement information, and stakeholder details, then outputs a complete timeline document with milestones, blackout periods, enforcement stages, owner assignments, and notification triggers. Use this prompt when you need a consistent, machine-readable timeline that can feed into status pages, changelogs, and internal stakeholder briefings. Do not use this prompt for drafting customer-facing prose notices or for generating legal compliance language without human review.

The ideal workflow starts with a concrete set of facts: the exact API endpoint, SDK method, or feature being deprecated; the replacement surface; the announcement date, brownout windows, and hard shutdown date; and the named owners for communication, engineering, and support. The prompt assembles these inputs into a phased timeline that prevents ambiguity about when consumers will experience enforcement. The output includes explicit blackout periods where the deprecated surface will return errors, notification triggers for each phase, and a RACI-style owner matrix. This structure is designed to be consumed by downstream automation—your status page can parse the JSON output to schedule banners, your changelog generator can insert milestones, and your internal briefing tool can route assignments to the correct teams.

Before using this prompt, validate that all input dates are consistent and logically ordered. A shutdown date that precedes a brownout window will produce a nonsensical timeline. The prompt includes a validation step that checks date ordering, but you should also verify that escalation contacts are current and that the replacement surface is actually available before publishing any timeline. If the deprecation carries regulatory implications, involves data retention commitments, or affects contractual SLAs, the output must pass through legal and compliance review before publication. The prompt produces operational structure, not legal assurance.

Do not use this prompt when you lack confirmed dates or when the replacement surface is still in design. Premature timelines erode developer trust and create unnecessary support burden. Also avoid this prompt for one-off, informal deprecation discussions—it is built for formal, multi-phase sunsets that require cross-team coordination. For drafting the actual customer-facing notice, use the API Deprecation Notice Drafting Prompt Template instead. For assessing which consumers are affected before you build the timeline, use the Deprecation Impact Assessment Prompt. This prompt sits between impact analysis and customer communication, producing the operational backbone that keeps all other deprecation artifacts consistent.

This template produces a phased deprecation timeline from your raw inputs. It forces the model to reason about date consistency, owner assignments, notification triggers, and enforcement stages before generating the output. Copy the template, replace each square-bracket placeholder with your specific details, and run it through your model. The output is a structured timeline you can review, validate, and publish.

codeCopy
You are a release manager generating a structured deprecation timeline for an API, SDK method, or feature. Your output must be accurate, internally consistent, and actionable. Do not invent dates, owners, or escalation paths. Use only the information provided in the placeholders below.

## INPUT
[FEATURE_NAME]: The exact name of the feature, endpoint, or method being deprecated.
[REPLACEMENT]: The recommended replacement, or "None" if no replacement exists.
[ANNOUNCEMENT_DATE]: The date the deprecation was or will be publicly announced (ISO 8601).
[EFFECTIVE_DATE]: The date the deprecation takes effect and warnings begin (ISO 8601).
[BROWNOUT_START]: The date of the first scheduled brownout or enforcement test, or "None" (ISO 8601).
[BROWNOUT_WINDOWS]: Description of brownout windows, e.g., "Every Tuesday 14:00-16:00 UTC for 4 weeks."
[SHUTDOWN_DATE]: The date the deprecated surface will be fully removed (ISO 8601).
[OWNER_TEAM]: The team responsible for executing the deprecation.
[OWNER_CONTACT]: Email or Slack channel for questions.
[ESCALATION_CONTACT]: Email or Slack channel for urgent issues.
[CONSUMER_IMPACT_SCOPE]: Description of affected consumers, e.g., "All users of the v1 /export endpoint."
[MIGRATION_GUIDE_URL]: Link to the migration guide.
[NOTIFICATION_CHANNELS]: List of channels where notifications will be sent, e.g., "email, status page, in-app banner."
[EXCEPTIONS_POLICY]: Policy for extension requests, or "No exceptions."

## CONSTRAINTS
- All dates must be in ISO 8601 format (YYYY-MM-DD).
- The announcement date must be before or equal to the effective date.
- The effective date must be before the shutdown date.
- Brownout dates, if present, must fall between the effective date and the shutdown date.
- If [REPLACEMENT] is "None," flag the deprecation as high-risk and recommend a replacement before shutdown.
- Do not fabricate owner names, contact details, or migration URLs.

## OUTPUT_SCHEMA
Return a JSON object with this exact structure:
{
  "deprecation_id": "string, generated as DEP-[FEATURE_NAME_SLUG]-[YYYY]",
  "feature_name": "string",
  "replacement": "string or null",
  "risk_level": "low | medium | high | critical",
  "risk_rationale": "string, one sentence explaining the risk classification",
  "phases": [
    {
      "phase": "announcement | warning | brownout | shutdown",
      "date": "ISO 8601 date or null",
      "description": "string, what happens in this phase",
      "consumer_impact": "string, what consumers experience",
      "notification_triggers": ["list of notification actions triggered in this phase"]
    }
  ],
  "owner_team": "string",
  "owner_contact": "string",
  "escalation_contact": "string",
  "migration_guide_url": "string or null",
  "exceptions_policy": "string",
  "date_consistency_check": {
    "passed": true,
    "issues": ["list of date consistency issues found, empty if passed"]
  }
}

## STEPS
1. Validate that all provided dates are in ISO 8601 format.
2. Check date ordering: announcement <= effective < shutdown.
3. If brownout dates are provided, verify they fall between effective and shutdown.
4. Classify risk level based on: presence of replacement, consumer impact scope, and time between announcement and shutdown.
5. Generate the timeline phases with owner assignments and notification triggers.
6. Run the date consistency check and include the result in the output.
7. If any validation fails, include the issue in `date_consistency_check.issues` and set `passed` to false.

Adaptation guidance: Replace every [PLACEHOLDER] with your actual deprecation details. If you don't have brownout dates, set [BROWNOUT_START] to "None" and [BROWNOUT_WINDOWS] to "None"—the model will skip that phase. The date_consistency_check field acts as a built-in validator; if it returns passed: false, fix the input dates before publishing the timeline. For high-risk or regulated deprecations, always route the output through human review before sending notifications to consumers.

The Deprecation Timeline Communication prompt is designed to be called from a release management or API governance system, not used as a one-off chat. The application layer should supply structured inputs—feature name, current version, replacement target, affected endpoints, and known blackout dates—and then validate the model's output against a strict schema before any human sees it. Treat the prompt as a structured document generator, not a conversational assistant. The output should be machine-readable enough to feed into downstream notification systems, status page updates, and internal stakeholder briefings.

Wire the prompt into a pipeline that performs the following steps: (1) Input assembly—collect required fields from your release tracking system (Jira, Linear, or an internal deprecation registry) and format them into the [DEPRECATION_CONTEXT] placeholder. Include the feature identifier, current version, target removal version, replacement API or feature, and any hard constraints like contractual blackout periods or regulatory freezes. (2) Prompt execution—send the assembled prompt to a capable model (GPT-4o, Claude 3.5 Sonnet, or equivalent) with temperature=0 to maximize date consistency and schema adherence. (3) Schema validation—parse the output against a JSON schema that requires milestones (array of objects with phase, date, owner, notification_trigger, consumer_impact), blackout_periods (array of date ranges), and escalation_contacts (array of objects with role, contact_method, response_sla). Reject any output missing required fields or containing date inconsistencies (e.g., a warning date after the shutdown date). (4) Retry with error context—if validation fails, feed the validation errors back into a retry prompt that includes the original input plus the specific schema violations. Limit retries to 2 attempts before escalating to a human release manager. (5) Human approval gate—even after schema validation passes, route the generated timeline to a release manager or API governance lead for review. The model can hallucinate plausible-sounding dates or miss organizational constraints that weren't in the input. The approval step should flag any milestone within 30 days of a known blackout period for extra scrutiny.

For production deployment, log every prompt execution with the input hash, model version, output, validation result, and reviewer decision. This audit trail is critical when a deprecation timeline is later disputed by an affected team or customer. If your organization uses a deprecation registry or API catalog, store the approved timeline back into that system as structured data—don't rely on the generated prose as the source of truth. The prompt output is a communication artifact derived from the structured timeline, not the timeline itself. When integrating with notification systems (email, status page, in-app banners), extract the milestone dates and notification triggers from the validated output and use them to schedule automated communications. Never automate sending deprecation notices directly from unvalidated model output.