Update API retirement and deletion prompts (#28494)

Author: FaithOmbongi

.github/prompts/author-api-docs/deprecate-retire.md

@@ -214,10 +214,15 @@ Retirement is the final stage of the API lifecycle — the deprecated API has re
 
 ### Inputs for retirement
 
-The Documentation Plan must explicitly identify:
-- Which resources (entity types, complex types) are being retired (marked as "Deleted" or "Removed")
-- Which API operation files are linked to the retired resources
-- **Dependency analysis for related types:** Complex types referenced as property return types and entity types referenced as relationship targets must be explicitly called out. The Documentation Plan must state whether each related type is also being retired or should be retained.
+Retirement can be triggered by:
+- **Schema change:** A Documentation Plan or changelog showing `ChangeType: "Deletion"` for entities, complex types, properties, relationships, actions, or functions
+- **Endpoint removal:** The product stops supporting an endpoint — this may not appear in the schema. The author will specify which endpoints are removed and the affected version(s).
+
+The Documentation Plan or author prompt must identify:
+- Which resources (entity types, complex types) are being retired
+- Which version(s): beta, v1.0, or both
+- The alternative API or resource (for redirects)
+- **Dependency analysis for related types:** Complex types referenced as property return types and entity types referenced as relationship targets may still be in use by other APIs. Only delete a related type if it is explicitly called out as retired — otherwise retain it.
 
 ### Retirement workflow
 
@@ -242,11 +247,14 @@ Based on the Documentation Plan, delete:
 3. **Permission include files** for the retired API operation files:
    - `api-reference/{version}/includes/permissions/{operation}-permissions.md` (naming may vary — match the include reference in each API operation file)
 
-4. **Complex type files** explicitly called out as retired/deleted in the Documentation Plan:
+4. **RBAC include files** for the retired API operation files (if they exist and not in use by other APIs):
+   - `api-reference/{version}/includes/rbac-for-apis/{rbac-file}.md` (match the include reference in each API operation file)
+
+5. **Complex type files** explicitly called out as retired/deleted in the Documentation Plan:
    - Only delete if the Documentation Plan explicitly marks the complex type as retired/deleted
    - If not explicitly called out as retired, retain the file
 
-5. **Enum files or sections** explicitly called out as retired/deleted in the Documentation Plan:
+6. **Enum files or sections** explicitly called out as retired/deleted in the Documentation Plan:
    - For standalone enum files: delete if explicitly marked as retired
    - For H3 sections in parent resources: removed when parent resource is deleted
    - For entries in global enums files (`enums.md`, `enums-{subnamespace}.md`): remove the enum section
@@ -277,12 +285,12 @@ Add redirects for **resource files that include Methods tables** (entity types)
     "redirections": [
         {
             "source_path": "api-reference/{version}/resources/{retired-resource}.md",
-            "redirect_url": "/graph/api/resources/{alternative-resource}",
+            "redirect_url": "/graph/api/resources/{alternative-resource}?view=graph-rest-{version}",
             "redirect_document_id": false
         },
         {
             "source_path": "api-reference/{version}/api/{retired-operation}.md",
-            "redirect_url": "/graph/api/{alternative-operation}",
+            "redirect_url": "/graph/api/{alternative-operation}?view=graph-rest-{version}",
             "redirect_document_id": false
         }
     ]
@@ -367,6 +375,7 @@ In addition to the [base quality checklist](common.md#base-quality-checklist), v
 - [ ] All resource files explicitly marked as retired/deleted are deleted
 - [ ] All API operation files linked to retired resources are deleted
 - [ ] All permission include files for retired operations are deleted
+- [ ] All RBAC include files for retired operations are deleted (if they existed and not in use by other APIs)
 - [ ] Complex types and enums only deleted if explicitly called out as retired in the Documentation Plan
 - [ ] References to retired resources removed from parent/related resource tables (Methods, Relationships, Properties)
 - [ ] TOC entries removed for deleted files

.github/prompts/review-api-docs.prompt.md

@@ -208,6 +208,18 @@ When reviewing resources that are part of a polymorphic hierarchy (base types wi
 
 Full rules: [common.md — Cross-file consistency validation](./author-api-docs/common.md#cross-file-consistency-validation) (point d) and [public-preview.md — Handling polymorphic entity types](./author-api-docs/public-preview.md#handling-polymorphic-entity-types)
 
+### Retirement (file deletion) review
+
+When a PR deletes API documentation files, validate:
+- **Completeness:** All API operation files, permission includes, and RBAC includes tied to a deleted entity type resource are also deleted
+- **Retained types:** Complex types and entity types referenced by the deleted resource are NOT deleted unless explicitly called out — they may be in use by other APIs
+- **Reference cleanup:** Deleted resources are removed from Methods tables, Relationships tables, and Properties tables in parent/related resource files
+- **Redirects:** Each deleted entity type resource file and API operation file has a redirect entry in the latest `.openpublishing.redirection.yyyy-mm.json` file in `redirects/`
+- **TOC:** Entries for deleted files removed from `toc.mapping.json`
+- **Changelog and What's New:** Entries with Change type "Deletion" are present
+
+Full rules: [deprecate-retire.md — Retirement workflow](./author-api-docs/deprecate-retire.md#retirement-api-removal) and [Retirement quality checklist](./author-api-docs/deprecate-retire.md#quality-checklist)
+
 ---
 
 ## Optional Context-Enhanced Review
@@ -341,6 +353,7 @@ If requested, provide specific edits to fix identified issues.
 
 **Special handling:**
 - Mixed scenarios: If both deprecation and other changes exist, flag this for the reviewer
+- Retirement (file deletions): Validate redirect entries, reference cleanup, and dependency safety — see [Retirement review](#retirement-file-deletion-review)
 - Autogenerated content: If file appears autogenerated (check metadata), validate that manual edits are appropriate
 - Permission files: These are typically autogenerated; validate format but don't require extensive review unless issues are evident