Breaking Change Communication Prompt Template

This prompt is designed for the moment after the breaking change has been decided and scoped, but before any consumer-facing communication has been drafted. The ideal user is an API product manager, developer relations engineer, or release manager who must coordinate a consistent message across email, developer portals, changelogs, and status pages. The prompt assumes you already know the technical details of the change—what endpoint, method, or behavior is breaking, the migration path, and the timeline. It does not help you decide whether to make a breaking change; it helps you communicate one that is already planned.

You should not use this prompt when the change is still under internal debate, when you lack confirmed dates or replacement endpoints, or when the audience is internal stakeholders who need a different level of detail. For internal briefings, use a stakeholder-specific prompt from the deprecation pillar. For drafting the actual deprecation notice rather than the multi-channel plan, use the API Deprecation Notice Drafting Prompt Template. This prompt also assumes you have access to escalation contacts, legal review requirements, and channel-specific formatting constraints—if those are missing, the output will contain placeholders that must be resolved before publication.

The prompt generates a structured communication plan, not the final copy for each channel. It classifies severity, maps the change to affected consumer cohorts, and produces channel-specific message outlines with before/after code comparisons and rollback instructions. Every output requires human review for tone calibration, escalation contact accuracy, and legal compliance. If your breaking change affects regulated data, financial transactions, or healthcare APIs, legal review is mandatory before any generated content reaches consumers. Start by gathering your change details, confirmed dates, replacement documentation, and channel requirements, then feed them into the template.

The template below is designed to produce a structured, multi-channel communication plan for a breaking change. It forces the model to classify severity, generate before/after code comparisons, and outline a rollback path. Before using it, you must gather the specific technical details of the change, the affected API surfaces, the migration timeline, and the exact escalation contacts. The prompt is a starting point for a draft, not a final publication. Every output requires human review for tone calibration, technical accuracy, and contact verification.

textCopy
You are a senior platform communications specialist. Your task is to draft a multi-channel communication plan for a breaking change to an API consumed by external developers.

# INPUTS
- Change Title: [CHANGE_TITLE]
- Change Description: [CHANGE_DESCRIPTION]
- Affected Endpoints/Methods: [AFFECTED_SURFACES]
- Replacement Endpoints/Methods: [REPLACEMENT_SURFACES]
- Migration Guide Link: [MIGRATION_GUIDE_URL]
- Effective Date: [EFFECTIVE_DATE]
- End-of-Life Date: [END_OF_LIFE_DATE]
- Escalation Contact: [ESCALATION_CONTACT]
- Rollback Procedure: [ROLLBACK_PROCEDURE]
- Consumer Impact Data: [CONSUMER_IMPACT_DATA]

# CONSTRAINTS
- Classify the change severity as CRITICAL, HIGH, MEDIUM, or LOW based on the consumer impact data.
- Generate a before/after code comparison for the primary affected endpoint.
- The tone must be direct and helpful, not alarming. Avoid passive voice and corporate jargon.
- All dates must be in ISO 8601 format (YYYY-MM-DD).
- Do not invent any contact information, dates, or technical details not provided in the inputs.

# OUTPUT SCHEMA
Return a single JSON object with the following structure:
{
  "severity_classification": {
    "level": "CRITICAL|HIGH|MEDIUM|LOW",
    "rationale": "string"
  },
  "communication_plan": {
    "email": {
      "subject": "string",
      "body": "string (markdown allowed)"
    },
    "developer_portal_banner": {
      "headline": "string",
      "body": "string",
      "cta_text": "string",
      "cta_link": "string"
    },
    "status_page_update": {
      "title": "string",
      "message": "string",
      "scheduled_for": "ISO 8601 date or null"
    },
    "changelog_entry": {
      "version": "string",
      "category": "breaking_change|deprecation|removal",
      "summary": "string"
    }
  },
  "code_comparison": {
    "description": "string",
    "before": "string (code block)",
    "after": "string (code block)"
  },
  "rollback_guidance": {
    "summary": "string",
    "steps": ["string"],
    "contact": "string"
  }
}

To adapt this template, replace every square-bracket placeholder with concrete data from your change management system. The [CONSUMER_IMPACT_DATA] field is critical for accurate severity classification; feed it with actual usage telemetry, not assumptions. After generating the draft, validate that all dates match your published deprecation schedule and that the escalation contact is a real, monitored channel. Run the output through a tone calibration review, especially for CRITICAL changes, to ensure the language is urgent but not panic-inducing. Finally, use the JSON output to programmatically populate your email system, status page, and developer portal CMS.

This prompt template is designed to be called programmatically as part of a release management or developer relations pipeline, not as a one-off chat interaction. The implementation harness should treat the prompt as a structured generation step that produces a multi-channel communication plan in a predictable JSON schema. Because the output will be distributed to external API consumers, the harness must enforce validation, human review, and approval gates before any message reaches a public channel.

Wire the prompt into your application by constructing a request that populates all required placeholders: [BREAKING_CHANGE_DETAILS] should be sourced from your changelog or API diff tooling, [AFFECTED_ENDPOINTS] from your API gateway or schema registry, and [MIGRATION_GUIDE_LINK] from your documentation pipeline. The model should be called with response_format set to a strict JSON schema that enforces the output structure—each communication channel (email, status page, in-app banner, developer portal) must be a separate object with channel, subject, body, severity_level, and send_date fields. Implement a validation layer that checks: (1) all required channels are present, (2) dates are consistent across channels and fall within the deprecation timeline, (3) code comparisons in the body are syntactically valid for the target language, and (4) escalation contact information is populated and matches your current on-call rotation.

Add a retry-and-repair loop for schema validation failures. If the model output fails JSON parsing or schema validation, feed the validation errors back into a repair prompt that includes the original input, the malformed output, and the specific field-level errors. Limit retries to 2 attempts before escalating to a human reviewer. For high-severity breaking changes (those classified as critical or breaking in your severity taxonomy), the harness must route the generated communication plan to a human approval queue before any messages are sent. The approval UI should display the full plan with channel previews, allow tone adjustments, and require explicit sign-off from both the API product manager and the developer relations lead. Log every generation attempt, validation result, retry, and approval decision to your prompt observability system for post-mortem analysis and regression testing against future prompt versions.

Choose a model with strong instruction-following and JSON mode support—GPT-4o or Claude 3.5 Sonnet are appropriate defaults. Do not use a model that lacks structured output guarantees, as malformed communication plans can cause missed notifications or inconsistent messaging to API consumers. If your platform requires on-premise or air-gapped deployment, validate that your chosen open-weight model can reliably produce the required JSON schema before promoting this prompt to production. The harness should also integrate with your incident communication tooling (e.g., Statuspage, PagerDuty, or a custom notification service) so that approved plans can be executed with a single action rather than manual copy-paste across channels.