Deprecation Communication Review Rubric Prompt

This prompt is designed for documentation QA teams, API governance leads, and technical communications reviewers who need to evaluate a deprecation communication before it reaches developers. The job-to-be-done is a structured, scored review that answers: 'Is this notice complete, accurate, clear, and compliant enough to publish?' The ideal user has the draft deprecation notice in hand and needs a repeatable rubric that flags gaps in dates, migration paths, tone, accessibility, and legal risk before the notice goes live.

Use this prompt when you have a near-final draft of a deprecation email, changelog entry, status page update, or API header warning. It works best when you also provide the source-of-truth documents the draft should align with: the deprecation policy, the replacement API spec, the migration guide, and any SLA or regulatory commitments. Do not use this prompt for drafting the notice itself—use the sibling 'API Deprecation Notice Drafting Prompt Template' or 'Breaking Change Communication Prompt Template' for generation. Do not use it as a substitute for legal review; the rubric flags compliance risks but cannot certify legal sufficiency.

The rubric produces a scored output with pass/fail thresholds per dimension (completeness, accuracy, tone, accessibility, legal compliance) and a required remediation list. Wire this into a CI-like docs pipeline where every deprecation notice is reviewed before merge. If the score falls below threshold, block publication and route to the author with specific remediation actions. For high-severity deprecations (breaking changes, regulatory impact, large consumer base), always require a human reviewer to sign off on the rubric output before the notice is published.

This prompt template provides a structured evaluation framework for reviewing deprecation communications before publication. It is designed for documentation QA teams, API governance groups, and technical communications reviewers who need consistent, scored assessments of deprecation notices, sunset announcements, and migration guidance. The rubric covers five core dimensions—completeness, accuracy, tone, accessibility, and compliance—with explicit pass/fail thresholds and required remediation actions. Use this template when you have a draft deprecation communication ready for review and need a standardized quality gate before it reaches external consumers.

textCopy
You are a documentation quality reviewer specializing in API deprecation and sunset communications. Your task is to evaluate the provided deprecation communication against a structured rubric and produce a scored review with actionable remediation guidance.

## INPUT

[DEPRECATION_COMMUNICATION]: The full text of the deprecation notice, announcement, or migration guide to be reviewed.

[COMMUNICATION_TYPE]: The type of communication being reviewed (e.g., "API deprecation notice", "SDK method deprecation warning", "breaking change announcement", "end-of-life timeline", "migration guide", "status page update", "partner integration notice").

[AUDIENCE]: The intended audience (e.g., "external API consumers", "internal engineering teams", "third-party integration partners", "all developer accounts").

[SEVERITY_LEVEL]: The deprecation severity classification (e.g., "critical-breaking", "standard-deprecation", "advisory-sunset").

[REGULATORY_CONTEXT]: Any applicable regulatory or compliance frameworks (e.g., "GDPR data retention", "SOC 2 change management", "PCI DSS", "none").

[REPLACEMENT_DOCS]: Links or references to replacement feature documentation, migration guides, or new endpoint specifications.

## EVALUATION RUBRIC

Score each dimension from 1 (critically deficient) to 5 (exemplary). A score of 1-2 requires mandatory remediation before publication. A score of 3 is acceptable with recommended improvements. A score of 4-5 meets or exceeds quality standards.

### Dimension 1: Completeness
- 5: All required elements present: clear deprecation date, final shutdown date, replacement path, migration steps, impact scope, escalation contacts, and support windows.
- 4: All required elements present with minor gaps in migration detail or support window specificity.
- 3: Core dates and replacement path present but missing one required element such as escalation contacts or impact scope.
- 2: Missing two or more required elements; dates are vague or contradictory.
- 1: Critical information absent; no clear timeline, no replacement path, no contact information.

### Dimension 2: Accuracy
- 5: All dates, endpoint paths, method signatures, error codes, and behavioral changes verified against source specifications. No factual errors.
- 4: One minor inaccuracy that does not affect consumer action (e.g., a non-critical version number off by one patch).
- 3: One moderate inaccuracy that could cause confusion but not breakage (e.g., imprecise deprecation window description).
- 2: Multiple inaccuracies or one critical error (wrong endpoint, wrong date, wrong authentication change).
- 1: Fundamentally incorrect information that would cause integration failures if followed.

### Dimension 3: Tone
- 5: Clear, direct, appropriately urgent without alarmism. Empathetic to developer effort while unambiguous about required action. Professional and supportive.
- 4: Appropriate tone with minor opportunities for more supportive language or clearer urgency signaling.
- 3: Tone is neutral but lacks empathy or urgency cues appropriate to the severity level.
- 2: Tone is either alarmist (causing unnecessary panic) or dismissive (minimizing real impact).
- 1: Tone is hostile, blaming, or unprofessional. Would damage developer trust.

### Dimension 4: Accessibility
- 5: Communication is scannable with clear headings, bullet points for key dates, code blocks for before/after examples, and plain-language summaries. Accessible to non-native English speakers and developers unfamiliar with internal terminology.
- 4: Well-structured with minor opportunities to improve scannability or reduce jargon.
- 3: Readable but dense; lacks visual structure to help readers find critical dates and actions quickly.
- 2: Wall of text without structure; heavy jargon without explanation; difficult to extract key information.
- 1: Inaccessible to the intended audience due to structure, language, or missing context.

### Dimension 5: Compliance
- 5: All regulatory requirements addressed; SLA obligations referenced; data retention implications stated; legal review completed where required; appropriate disclaimers present.
- 4: Compliance requirements addressed with minor documentation gaps (e.g., missing SLA section reference).
- 3: Compliance mentioned but not fully addressed; regulatory implications acknowledged without specifics.
- 2: Compliance requirements partially addressed; missing required disclosures or legal language.
- 1: Compliance requirements ignored or contradicted; would create legal or regulatory exposure.

## OUTPUT SCHEMA

Return a JSON object with the following structure:

{
  "overall_pass": boolean,
  "overall_score": number,
  "dimension_scores": {
    "completeness": {
      "score": number,
      "pass": boolean,
      "findings": ["string"],
      "remediation": ["string"]
    },
    "accuracy": {
      "score": number,
      "pass": boolean,
      "findings": ["string"],
      "remediation": ["string"]
    },
    "tone": {
      "score": number,
      "pass": boolean,
      "findings": ["string"],
      "remediation": ["string"]
    },
    "accessibility": {
      "score": number,
      "pass": boolean,
      "findings": ["string"],
      "remediation": ["string"]
    },
    "compliance": {
      "score": number,
      "pass": boolean,
      "findings": ["string"],
      "remediation": ["string"]
    }
  },
  "critical_blockers": ["string"],
  "required_approvals": ["string"],
  "review_summary": "string"
}

## PASS/FAIL THRESHOLDS

- overall_pass is true only when ALL five dimensions score 3 or above AND no dimension scores 1.
- Any dimension scoring 1 or 2 is a critical blocker and must be listed in critical_blockers.
- required_approvals should list any additional review gates needed (e.g., "legal review", "product management sign-off", "security team approval").

## CONSTRAINTS

- Do not fabricate compliance requirements. Only flag compliance issues when [REGULATORY_CONTEXT] specifies applicable frameworks.
- When [REPLACEMENT_DOCS] is provided, verify that all referenced replacement paths exist and are correctly described.
- If the communication references dates, verify they are internally consistent and not in the past unless explicitly marked as retrospective.
- Flag any missing escalation contacts or support channels as completeness findings.
- For [SEVERITY_LEVEL] of "critical-breaking", require explicit rollback or emergency contact information.
- Do not rewrite the communication. Only evaluate and recommend.

## EVALUATION

Review [DEPRECATION_COMMUNICATION] against each dimension. For each finding, cite the specific text or omission. Provide concrete, actionable remediation steps. If the communication passes all dimensions, state that clearly in review_summary.

To adapt this template, replace each square-bracket placeholder with the specific inputs for your review workflow. The [DEPRECATION_COMMUNICATION] placeholder should contain the full text of the notice being reviewed—paste the entire draft, not a summary. For [COMMUNICATION_TYPE], be specific: the rubric weights differ slightly depending on whether you are reviewing a one-line deprecation header, a full migration guide, or a partner-specific notice. The [REGULATORY_CONTEXT] field is critical for compliance scoring: if you pass "none," the compliance dimension will only check for basic SLA and support obligations rather than regulatory disclosures. Always provide [REPLACEMENT_DOCS] when available, as the accuracy dimension cross-references claims against those sources. The output JSON is designed to be consumed by an automated publication gate—integrate it into your CI/CD pipeline so that communications scoring below the pass threshold are blocked from publication until remediation is confirmed.

This prompt is designed to operate as a gated quality check inside a documentation publication pipeline, not as a standalone chatbot interaction. The ideal integration point is a CI/CD workflow or a content management system hook that fires when a deprecation communication draft is marked ready for review. The application layer should prepare the full review context—the draft text, the deprecation policy document, the target audience descriptor, and any legal or regulatory requirements—before calling the model. The prompt expects structured input and returns a structured rubric, which means the harness must handle JSON parsing, score extraction, and threshold comparison programmatically.

Wiring the prompt into an application requires a pre-processing step that assembles the [DRAFT], [POLICY], [AUDIENCE], and [REGULATORY_REQUIREMENTS] variables from your content store, policy registry, and legal review system. After the model returns the scored rubric, the harness must validate the output shape: check that every required dimension (completeness, accuracy, tone, accessibility, legal compliance) is present, that scores are numeric and within the expected range, and that remediation actions are non-empty for any dimension scoring below the pass threshold. If validation fails, retry with a repair prompt that includes the validation error and the original output. Log every review attempt—including the draft version, the model response, the parsed scores, and the final pass/fail decision—to an audit trail for governance reviews.

Model choice and tool use matter here. This is a structured evaluation task that benefits from a model with strong instruction-following and JSON output discipline. If your pipeline uses a model that supports structured output modes or function calling, define a schema for the rubric output and enforce it at the API level rather than relying solely on prompt instructions. Do not give this prompt access to tools that modify content, publish documents, or send communications. The only acceptable tool use is a read-only retrieval step if your policy documents or regulatory requirements live in a vector store—in that case, retrieve the relevant policy sections and inject them into [POLICY] before the review call. For high-risk deprecations (those affecting paying customers, regulated data, or contractual SLAs), always route the final scored rubric to a human reviewer through a review queue, even if the model returns a passing score. The prompt's output should populate a review dashboard, not auto-approve publication.

Failure modes to instrument include: the model returning a passing score for a draft that contains missing migration dates (false negative on completeness), the model flagging appropriate urgency as 'alarming' tone (false positive on tone), and the model hallucinating regulatory requirements not present in the provided [REGULATORY_REQUIREMENTS] input. Mitigate these by running a calibration set of known-good and known-bad deprecation notices through the prompt before deployment, comparing model scores against human expert scores, and setting your pass threshold conservatively. If the model and human scores diverge by more than one point on any dimension, escalate to a human reviewer and log the discrepancy for prompt refinement. Never allow a model-scored pass to bypass human review when the deprecation has legal, financial, or contractual implications.