/author + /reviewAPIDocs edits (#28507)

- Handling long-running operations.

Author: FaithOmbongi

.github/prompts/author-api-docs/common.md

@@ -603,6 +603,19 @@ Use the following format when reporting file processing results, so output is co
 ⚠️ Blocked: [list with reasons, or "None"]
 ```
 
+**Mid-phase validation** (required at every ⏸ phase gate, before moving to the next phase):
+
+Re-read each file completed in the current phase and verify it meets expectations for its file type. Output a validation checklist:
+
+```
+✅ Phase [N] Validation
+- [file1.md]: H1 ✓ | Namespace ✓ | Properties table ✓ | JSON representation ✓
+- [file2.md]: H1 ✓ | Namespace ✓ | Permissions ✓ | HTTP request ✓ | Examples ✓
+- [file3.md]: H1 ✓ | Namespace ✓ | Properties table ✗ (missing "newProperty") — FIXING
+```
+
+Fix any failures before proceeding to the next phase. Do not defer fixes to end-of-session.
+
 ## State Tracking
 
 Maintain a running progress tracker throughout the session. After each file or batch of files, update and display:
@@ -625,8 +638,9 @@ For Documentation Plans with many files (10+):
 1. **Group by type:** resources, API methods, enumerations, permissions, supporting files
 2. **Process in batches of 5 files** — complete all steps for each file before moving to the next
 3. **After each batch**, output a phase status summary (see [Structured Output Format](#structured-output-format))
-4. **Present the execution plan upfront** and proceed unless the author objects — avoid blocking confirmations for each batch when the Documentation Plan is clear
-5. **If the plan exceeds 20 files**, create a numbered task list at the start, group into batches, and checkpoint progress after each batch
+4. **Verify each batch before proceeding:** Re-read every file in the completed batch and confirm it contains the expected sections (e.g., H1, namespace, Permissions, HTTP request, Examples for API files; H1, namespace, Properties table, JSON representation for resource files). Fix any issues before starting the next batch.
+5. **Present the execution plan upfront** and proceed unless the author objects — avoid blocking confirmations for each batch when the Documentation Plan is clear
+6. **If the plan exceeds 20 files**, after the first batch completes and is verified, **stop and ask the author to confirm quality** before continuing. This catches systematic errors early.
 
 ## Decision Trees for Ambiguous Cases
 
@@ -702,6 +716,8 @@ Report any inconsistencies in the final summary to the author.
 
 The following checks apply to every documentation scenario. Scenario-specific checklists add additional items on top of these.
 
+> **IMPORTANT:** For each checklist item, re-read the actual file content to confirm — do not check items from memory.
+
 **For all files (new and updated):**
 - [ ] All required sections are present and in correct order
 - [ ] Headings match the expected format

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

@@ -297,6 +297,8 @@ Group files by type:
 
 For each file, apply the appropriate review checklist from above.
 
+**For PRs with 15+ changed files:** Review in batches of 10 files. After each batch, output findings so far before continuing to the next batch. This keeps context focused and prevents quality degradation on later files.
+
 ### Step 4: Run Validation Scripts
 
 Run automated validation scripts to ensure compliance (see [Common Process: Validation](#common-process-validation)):
@@ -318,6 +320,8 @@ Use these criteria consistently when categorizing findings:
 
 ### Step 6: Report Findings
 
+> **IMPORTANT:** Before finalizing the report, re-read each reviewed file to confirm your findings. Do not report issues or approvals from memory alone.
+
 Provide a structured review report:
 
 **Summary:**