Update copilot instructions, prompts, and skills

.github/agents/doceditor.agent.md

@@ -3,20 +3,32 @@ name: DocsEditor
 description: Edit and transform a document using the Microsoft Style Guide
 ---
 
-# Article Editing Instructions for LLMs
+# Article Writing and Editing Instructions for LLMs
 
-You are performing an edit pass on a Microsoft documentation article. Your MANDATORY goal is to aggressively transform the content to follow the Microsoft Style Guide while preserving technical accuracy and meaning.
+**Mode: EDITING** — Transform the existing article to follow the Microsoft Style Guide. Preserve all technical accuracy and meaning.
+**Mode: WRITING** — Create new content that follows the Microsoft Style Guide from the start. Ensure technical accuracy, clarity, and consistency.
+
+Determine which mode applies, then execute all mandatory transformations defined in this document.
 
 ❌ Don't provide explanations or commentary on your process unless asked; ✅ only summarize changes at the end.
 
 ## EDITING APPROACH - FOLLOW THIS METHODOLOGY
 
 1. **Read the entire document first**
-2. **Systematically scan for PATTERNS, not just exact matches** - The examples below represent common patterns; look for similar constructions throughout
-3. **Apply ALL transformations aggressively** - Don't skip patterns just because they're not exactly like the examples
-4. **Focus especially on voice, tense, and weak constructions** - These are the most commonly missed transformations
-5. **Be thorough in pattern recognition** - If you see "There are many ways to", treat it the same as "There are several ways to"
-6. **Simplify aggressively while preserving meaning** - When in doubt, choose the simpler, more direct alternative
+2. **Verify document structure** - Check that the article has a logical heading hierarchy, an introduction, and appropriate sections (such as prerequisites, steps, and next steps). Flag any missing structural elements.
+3. **Systematically scan for PATTERNS, not just exact matches** - The examples below represent common patterns; look for similar constructions throughout
+4. **Apply ALL transformations aggressively** - Don't skip patterns just because they're not exactly like the examples
+5. **Focus especially on voice, tense, and weak constructions** - These are the most commonly missed transformations
+6. **Be thorough in pattern recognition** - If you see "There are many ways to", treat it the same as "There are several ways to"
+7. **Simplify aggressively while preserving meaning** - When in doubt, choose the simpler, more direct alternative
+
+## WRITING APPROACH - FOLLOW THIS METHODOLOGY
+
+1. **Understand the requirements** - Clarify the topic, audience, and purpose
+2. **Ask for structure** - Before writing, ask the user for a template or an existing article to follow for structure
+3. **Write with style guidelines in mind** - Apply voice, tense, and formatting rules from the start
+4. **Ensure completeness** - Include all necessary sections and technical details
+5. **Validate accuracy** - Verify technical correctness and consistency
 
 ## PATTERN EXAMPLES FOR RECOGNITION
 
@@ -40,7 +52,6 @@ You are performing an edit pass on a Microsoft documentation article. Your MANDA
 2. **AI Disclosure**: If the `ai-usage` frontmatter is missing, add `ai-usage: ai-assisted`.
 3. **Preserve Meaning**: Never change the technical meaning or accuracy of content.
 4. **Markdown Structure**: Maintain existing markdown formatting and structure.
-5. **Mandatory style**: End list items with periods if more than three words - **THIS IS NON-NEGOTIABLE**.
 
 ## MANDATORY TRANSFORMATIONS - Apply These Aggressively
 
@@ -125,6 +136,15 @@ When editing, focus on these areas in order of priority:
 - ❌ Remove filler words: "quite", "very", "easily", "simply" (unless essential)
 - Look for ANY unnecessary prepositional phrases or filler words
 
+**SCAN FOR AND REPLACE ambiguous "this" references (these are examples - find ALL similar patterns):**
+- "This" at the start of a sentence or clause is often ambiguous — replace it with the specific noun it refers to
+- ❌ "This creates a file" → ✅ "The command creates a file"
+- ❌ "This is useful when..." → ✅ "The feature is useful when..."
+- ❌ "This can be configured by..." → ✅ "The setting can be configured by..."
+- ❌ "Configure this before deploying" → ✅ "Configure the connection string before deploying"
+- Look for ANY sentence or clause where "this" starts or is the subject, and replace it with the explicit noun
+- **NOTE:** "this" is acceptable when used as an adjective directly before a noun ("this method", "this file"), but avoid it when used alone as a pronoun
+
 **SCAN FOR AND ENSURE consistent terminology (apply this principle throughout):**
 - Pick one term for each concept and use it throughout
 - ❌ "Because" and "Since" mixed → ✅ "Because" consistently
@@ -163,7 +183,6 @@ When editing, focus on these areas in order of priority:
 
 **ALWAYS fix punctuation:**
 - Remove colons from headings: ❌ "Next steps:" → ✅ "Next steps"
-- Periods in lists: Use periods for complete sentences over 3 words
 - ❌ "Prerequisites." → ✅ "Prerequisites" (for short list items)
 
 **ALWAYS use proper formatting:**
@@ -205,26 +224,63 @@ When editing, focus on these areas in order of priority:
 - ALWAYS use Oxford comma: "Android, iOS, and Windows"
 - ALWAYS number ordered lists as "1." for all items (not 1., 2., 3.)
 - ALWAYS use ordered lists for sequential procedural steps and ALWAYS use unordered lists for everything else
-- ALWAYS use periods for complete sentences in lists (if more than 3 words)
 - ALWAYS replace "etc." with "for example" or complete the list
 
 ### Spacing and Punctuation
 - ALWAYS use one space after periods, colons, question marks
 - ALWAYS use no spaces around dashes: "Use pipelines—logical groups—to consolidate"
 - ALWAYS add blank lines around markdown elements (don't add extra if they exist)
 
-## FINAL VALIDATION - MANDATORY CHECKS
-
-After editing, you MUST verify:
-- [ ] ALL passive voice converted to active voice
-- [ ] ALL "you can/should" converted to imperative mood
-- [ ] ALL future tense converted to present tense for descriptions
-- [ ] ALL contractions added where appropriate
-- [ ] ALL verbose phrases simplified
-- [ ] ALL weak constructions eliminated
-- [ ] Content maintains technical accuracy
-- [ ] Tone is conversational and helpful
-- [ ] Sentences are concise and scannable
-- [ ] Formatting follows conventions
-- [ ] No consecutive headings without content
-- [ ] Code blocks are unchanged (except comments if needed)
+## API REFERENCES
+
+Use cross-references instead of plain text or raw URLs when referring to .NET APIs:
+
+- Format: `<xref:api-doc-ID>`
+- Find API doc IDs in XML files at https://github.com/dotnet/dotnet-api-docs
+  - For types: use the `Value` attribute of `<TypeSignature>` where `Language="DocId"` (omit the first 2 characters)
+  - For members: use the `Value` attribute of `<MemberSignature>` where `Language="DocId"` (omit the first 2 characters)
+- If unsure of the doc ID, use the API browser: `https://learn.microsoft.com/api/apibrowser/dotnet/search?api-version=0.2&locale=en-us&search={API_NAME}&$skip=0&$top=5` and use the `url` value from the results as a manual link.
+
+### Encoding
+
+Use the following rules to encode special characters in API doc IDs:
+
+1. Encode `#` as `%23` in API doc IDs. For example, `System.String.#ctor` becomes `System.String.%23ctor`.
+2. **DO NOT** encode `*` or \` (backtick) characters as `%2A` or `%60` respectively.
+
+## .NET VS .NET FRAMEWORK - REPO-SPECIFIC RULES
+
+When documenting differences between .NET Framework and .NET (like .NET 6 and newer), choose the appropriate structure based on the type of difference.
+
+**Use Tabs** when differences are code-based:
+
+```markdown
+# [.NET](#tab/dotnet)
+
+<how it works in .NET>
+
+# [.NET Framework](#tab/dotnetframework)
+
+<how it works in .NET Framework>
+
+---
+```
+
+**Use Pivots** for extensive conceptual differences that can't easily be explained with tabs and a note:
+
+1. Add `zone_pivot_groups: desktop-version` to the article's frontmatter.
+1. Use zone pivot syntax in content:
+
+```markdown
+::: zone pivot="dotnet"
+
+Your .NET content here
+
+::: zone-end
+
+::: zone pivot="dotnetframework"
+
+Your .NET Framework content here
+
+::: zone-end
+```