How to Prompt AI to Write a Deprecation Notice

A deprecation notice has to carry four facts in a fixed order: what is going away, the exact date it stops working, what replaces it, and what breaks if the reader does nothing. Prompt for those four in that order and you get a usable notice on the first pass. Ask for "a deprecation notice" and you get three paragraphs of apology wrapped around a date the reader has to hunt for.

The difference is not writing quality. It is that models default to softening bad news, and a deprecation notice is a document where softening is the failure.

Why the default output is wrong

Ask any model to write a deprecation notice cold and you will get some version of this:

We're excited to share that we're continuously evolving our platform to better serve you. As part of this journey, we'll be making some changes to our Legacy Reports API. We appreciate your understanding and are here to support you through this transition.

Every sentence is doing emotional work and none is doing informational work. There is no date, no replacement, and no statement of consequence. A developer reading it learns that something is happening to something, eventually.

This happens because "notice" reads to the model as "announcement", and announcements are optimistic by convention. The fix is to specify the document's job rather than its genre.

The four facts, in order

Order matters because readers skim and stop. Put the date third and half your audience never reaches it.

1. What is being deprecated. The exact name, version, or endpoint. Not "some changes to our API".

2. When it stops working. A specific date. If there are two dates, a soft deprecation and a hard shutoff, give both and label which is which.

3. What to use instead. A named replacement with a link. If there is no replacement, say that plainly, because the reader's next action is completely different.

4. What breaks if they ignore this. The concrete failure. "Requests will return 410 Gone" rather than "functionality may be impacted".

Anything else, the reasoning, the thanks, the support contact, goes after those four. It is not forbidden, it is just not first.

A prompt template that works

Write a deprecation notice. This is a factual notice, not an announcement.
Do not open with enthusiasm or thanks.

THING BEING DEPRECATED: [exact name/version/endpoint]
DEPRECATION DATE (stops being recommended): [date]
SHUTOFF DATE (stops working): [date]
REPLACEMENT: [name + link, or "none" if there is none]
WHAT BREAKS ON THE SHUTOFF DATE: [concrete failure, e.g. HTTP 410]
WHO IS AFFECTED: [segment, e.g. "anyone calling v1 endpoints"]
MIGRATION EFFORT: [honest estimate, e.g. "one-line change" or "requires reworking pagination"]

Structure:
- One sentence stating what is going away and when it stops working.
- What to do instead, with the replacement named.
- What happens if they do nothing.
- Migration detail.
- Reasoning, only if it helps the reader decide something.

Rules:
- Lead with the fact, not the feeling.
- Every date is explicit. Never "soon", "in the coming months", "shortly".
- Do not apologise more than once, if at all.
- Do not claim the change benefits the reader unless it demonstrably does.

The last rule earns its place. Models reliably assert that a removal is an improvement for the person losing the feature. Sometimes that is true. Usually the improvement accrues to you, and readers can tell.

Before and after

Same facts, the template applied.

Before, model default:

We're excited to share that we're continuously evolving our platform. As part of this journey, we'll be making some changes to our Legacy Reports API. We appreciate your understanding and are here to support you through this transition.

After:

The Legacy Reports API (/v1/reports) stops working on 3 March 2027. It is deprecated as of today and will return HTTP 410 Gone after that date.

>

Use /v2/reports instead. It returns the same fields with two changes: created is now ISO 8601 rather than a Unix timestamp, and results are cursor-paginated rather than offset-paginated.

>

If you do nothing, any integration calling /v1/reports will start failing on 3 March 2027. There is no grace period and no automatic redirect.

>

Most migrations are a one-line base URL change plus a date parse. Pagination is the part that takes real work, and the migration guide has a worked example.

>

We are removing v1 because it cannot support the row limits customers are now hitting. It is not being kept in parallel.

The second version is shorter, and a reader can act on it without asking a follow-up question. That is the whole standard.

Where teams get this wrong

Hedged dates. "In the coming months" is not a date. It converts a decision into a monitoring task for every customer you have, and they will not do it.

Burying the consequence. If the failure mode is a hard error, say so in the first three sentences. Readers triage by severity, and they cannot triage what you have not told them.

No replacement named, no acknowledgement of that. If nothing replaces the feature, that is legitimate and the notice must say it outright. Silence reads as an oversight and generates support load.

Over-apologising. One acknowledgement is fine. Three reads as guilt, and guilt reads as instability.

Announcing once. A notice is a campaign, not an email. The prompt above produces the artifact; you still need to send it more than once and put the date somewhere durable, such as your product changelog.

Machine-readable deprecation, while you are here

If you are deprecating an HTTP API, the notice has a technical counterpart. RFC 8594 defines a Sunset HTTP header carrying the date a resource becomes unresponsive, alongside a Deprecation header and link relations pointing at the replacement.

Shipping those headers alongside the written notice means integrators can detect the deadline programmatically rather than relying on someone having read an email in March. It costs almost nothing and it is the single highest-leverage thing you can add to a deprecation.

Related prompting patterns

A deprecation notice sits in a family of documents where the model's instinct to be pleasant works against you. Release notes have the opposite problem, where the default is too terse rather than too soft, and incident updates share the deprecation notice's need to lead with consequence.

The general technique underneath all three is specifying the document's job and its reader's next action, rather than its genre. More on that in the prompt engineering guide.

If the deprecation is a whole feature rather than an endpoint, the writing is the last step of a longer decision. How to sunset an AI feature covers the part that comes first.

FAQ

What should a deprecation notice always include?

What is going away, the exact date it stops working, what replaces it, and what breaks if the reader does nothing. In that order, before anything else.

How far in advance should I send a deprecation notice?

Long enough for the migration effort you are asking for. A one-line change can be weeks. Anything requiring reworking how a customer's integration paginates or authenticates should be months, and should be repeated.

Should the notice explain why we are deprecating it?

Only if the reason helps the reader decide something. "It cannot support the row limits customers now hit" is useful because it tells them the old version was going to fail them anyway. "To better serve you" is not.

How do I stop AI writing an apologetic deprecation notice?

Tell it explicitly that this is a factual notice rather than an announcement, and forbid opening with enthusiasm or thanks. Without that instruction, models treat "notice" as a synonym for "announcement".

What if there is no replacement for the deprecated feature?

Say so in the notice, in the position where the replacement would go. Readers will assume you forgot to mention it otherwise, and you will field the question anyway.