Merge pull request #28023 from microsoftgraph/author-api-docs-prompt-correct-changelog-guidance

Author API docs prompt - Correct changelog guidance

Author: FaithOmbongi

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

@@ -79,11 +79,56 @@ After authoring documentation, update the appropriate changelog file in the `cha
   }
   ```
 
-**Step 3: Copy changelog records**
-- Copy the ChangeList records from the autogenerated changelog
-- Add them to the appropriate changelog file in the `changelog/` folder
-- Ensure the WorkloadArea and SubArea match the autogenerated file
-- Use "beta" for Version in Scenario 1, "v1.0" for Version in Scenario 2
+**Step 3: Copy the complete changelog record**
+- **IMPORTANT:** A changelog record is NOT just the ChangeList array. A complete changelog record consists of:
+  - `ChangeList` array (containing individual change items)
+  - `Id` (unique GUID for this set of changes)
+  - `Cloud` (e.g., "Prod")
+  - `Version` (e.g., "beta" or "v1.0")
+  - `CreatedDateTime` (ISO-8601 DateTime)
+  - `WorkloadArea` (e.g., "Security")
+  - `SubArea` (may be empty string)
+
+- **How to copy the record:**
+  1. Open the autogenerated changelog file from `temp-docstubs/` (e.g., `changelog_*.json` or `Microsoft.*.json`)
+  2. Locate the complete record object inside the `"changelog"` array (usually lines 3 to the closing brace of that object)
+  3. Copy the ENTIRE record object, including:
+     - Opening brace `{`
+     - The complete `ChangeList` array with all its items
+     - All metadata properties (`Id`, `Cloud`, `Version`, `CreatedDateTime`, `WorkloadArea`, `SubArea`)
+     - Closing brace `}`
+  4. Open the target changelog file in `changelog/{prefix}.json`
+  5. Paste the complete record as the FIRST item in the `"changelog"` array (after the opening `[`)
+  6. Ensure proper JSON formatting with commas between records
+
+- **Example of what to copy (complete record):**
+  ```json
+  {
+    "ChangeList": [
+      {
+        "Id": "1e2218aa-5dbc-4c74-a0fe-1d06e90b451c",
+        "ApiChange": "Property",
+        "ChangedApiName": "newProperty",
+        "ChangeType": "Addition",
+        "Description": "Added the **newProperty** property...",
+        "Target": "resourceName"
+      }
+    ],
+    "Id": "1e2218aa-5dbc-4c74-a0fe-1d06e90b451c",
+    "Cloud": "Prod",
+    "Version": "beta",
+    "CreatedDateTime": "2026-01-07T08:37:50.5865153Z",
+    "WorkloadArea": "Security",
+    "SubArea": ""
+  }
+  ```
+
+- **DO NOT:**
+  - Copy only the ChangeList items and insert them into an existing record
+  - Modify the Id, CreatedDateTime, or other metadata from the autogenerated file
+  - Create a new record structure manually
+
+- **Result:** The changelog file should have the new record added at the beginning of the changelog array, with all subsequent records following it
 
 ### Common Process: Updating What's New