How do you retire a policy rule that other teams' pipelines import, without breaking them?

## A shared rule is an interface Once other teams' pipelines import your rule, you no longer own a file - you own a published surface with consumers you cannot see from your own repository. Deleting it is a breaking change to their build, and the discipline that applies is the one you would apply to any interface with callers: know who they are, tell them before you move, give them a fixed date, and honour it. ## Separate the control from its implementation The single most important distinction, and the one candidates skip: - **The implementation is being retired.** The requirement still stands; a newer rule, a platform default, or an upstream check now enforces it. This is a migration, and the burden on you is a mapping: what replaces it, what consumers must change, and what different outcomes they should expect. - **The control is being retired.** The organisation has decided this requirement no longer applies, or no longer applies at this cost. That is a risk decision, and it needs a named owner and a record. Retiring a control by deleting a file is how an organisation loses the ability to explain, later, whether a gap was chosen or accidental. Both are legitimate. Conflating them is not. ## The mechanics that make it non-breaking 1. **Enumerate consumers.** Search the organisation for imports and references, and cross-check with the engine's own telemetry for who actually evaluates the rule. The two lists differ: repositories that import it but no longer run, and callers you did not know existed. 2. **Publish a date, not an intention.** 'Deprecated, will be removed in a future release' produces zero migrations. A calendar date produces work, because it can be put in a sprint. 3. **Size the notice to the slowest consumer, not the average.** A team that ships quarterly needs more than one sprint. This is a judgment call: too short and you break people who did nothing wrong; too long and everyone defers until the last week anyway, which argues for a notice long enough to be reasonable and short enough to stay real. 4. **Warn where it will be read.** The deprecation notice belongs in the decision output the consumer's pipeline already prints - the same place the rule's verdicts appear - because that is the channel their engineers actually watch. Mail and chat announcements supplement it; they do not replace it. 5. **Provide the migration note with the announcement, not after it.** What replaces it, the mapping from old outcome to new, and the one-line answer for a team that finds nothing replaces it. 6. **Delete on the date.** Do not leave an always-allow stub. A rule that can never deny is indistinguishable from a working rule in every dashboard, keeps consumers importing something with no meaning, and quietly creates the false coverage this whole practice exists to prevent. ## Record the retirement as evidence Whatever the reason, write down that this rule enforced this control from this date to that date, and why it stopped. Twelve months later, a reviewer looking at a gap in the record cannot otherwise tell the difference between a control that was deliberately retired and one that silently broke - and those two have very different consequences. This is the cheapest artefact in the whole exercise and the one most often skipped. ## Make retirement routine, not heroic The reason retirement is hard is almost always that it is rare. A standing review - quarterly is the common cadence - that walks the rule set and asks three questions of each rule turns it into ordinary maintenance: is the requirement still real, is the rule still matching anything, and is this still the right place to enforce it. Two supporting habits make that review possible: every rule gets a named owner and a review date when it is created, and every rule's origin - the requirement it implements - is recorded with it. Without those, the review degenerates into a room of people who do not know why any of the rules exist and therefore delete none of them. ## The judgment a lead is expected to own Both failure modes are real and they pull opposite ways. Hold the date too rigidly and you break a team mid-release-freeze over a rule that was your idea. Slip it whenever anyone asks and the date stops meaning anything, the rule set never shrinks, and the review becomes theatre. The resolution that usually survives contact: the **date** holds, and what flexes is **who does the work** - the platform team lands the migration in the consumers' repositories rather than moving the deadline. That converts an argument about calendars into an allocation of effort, which is a thing you can actually decide. Where a consumer genuinely cannot move, the honest options are a scoped, dated carve-out owned by you, or an explicit decision to slip the date once, announced as such - never a quiet extension that nobody records.