Enforce gerund-avoidance and reason-first sentence structure in Copilot writing style rules

.github/agents/breakingchange.agent.md

@@ -9,6 +9,8 @@ You are a documentation specialist focused on breaking change articles. Focus on
 - Document ONLY modern .NET breaking changes. That is, ignore docs under [`docs/framework/migration-guide`](https://github.com/dotnet/docs/tree/main/docs/framework/migration-guide) (which are for legacy .NET Framework).
 - Make content clear and concise.
 - In addition to adding the new article, update any related articles that describe or use the affected feature or API to mention the new behavior.
+- **Avoid gerunds** — Don't use -ing verb forms where they obscure who performs the action. Write "When you call the method..." instead of "When calling the method...".
+- **Lead with reasons** — Put the reason or purpose at the beginning of a sentence. Write "To maintain compatibility, update your code" instead of "Update your code to maintain compatibility".
 
 ## Document structure
 

.github/agents/docseditor.agent.md

@@ -87,6 +87,13 @@ When editing, focus on these areas in order of priority:
 - ❌ "Once you have completed the setup" → ✅ "Once you complete the setup"
 - Look for ANY pattern with: "have/has + past participle", "have/has been + verb-ing"
 
+**SCAN FOR AND CONVERT gerund phrases to clearer constructions that name the actor (these are examples - find ALL similar patterns):**
+- ❌ "When working with the API..." → ✅ "When you work with the API..."
+- ❌ "Before deploying the application..." → ✅ "Before you deploy the application..."
+- ❌ "After configuring the settings..." → ✅ "After you configure the settings..."
+- ❌ "By using this method..." → ✅ "When you use this method..."
+- Look for ANY introductory or dependent clause that uses an -ing verb form (including clauses introduced by words such as "when," "before," "after," or "by") and replace it with "<person or entity performing the action> + verb"
+
 **SCAN FOR AND ELIMINATE ALL weak constructions (these are examples - find ALL similar patterns):**
 - ❌ "There are three ways to..." → ✅ "Use these three methods..."
 - ❌ "It's possible to..." → ✅ "You can..." or start with the action
@@ -169,6 +176,13 @@ When editing, focus on these areas in order of priority:
 - ❌ "When replacing Newtonsoft the plan switches..." → ✅ "When replacing Newtonsoft, the plan switches..."
 - ❌ "In chat you see that it opened..." → ✅ "In chat, you see that it opened..."
 
+**ALWAYS lead with reasons and purposes, not end sentences with them:**
+- ❌ "Cache the instance for better performance" → ✅ "For better performance, cache the instance"
+- ❌ "Use HTTPS to improve security" → ✅ "To improve security, use HTTPS"
+- ❌ "Install the package to enable the feature" → ✅ "To enable the feature, install the package"
+- When a sentence ends with a clearly identifiable purpose clause, usually a "to ..." or "so that ..." clause, move that clause to the beginning and add a comma after it
+- Preserve the original technical meaning exactly; if moving the clause would change, narrow, or overstate the meaning, leave the sentence as written
+
 **ALWAYS make next steps obvious:**
 - Use clear transitions
 - Number steps when there's a sequence

.github/copilot-instructions.md

@@ -95,6 +95,13 @@ When adapting content from external sources like blog posts into documentation:
 - Note all generated sections requiring expert review.
 - Clear warnings about any uncertainties.
 
+## Writing Style
+
+When you create or edit documentation, apply these style rules to the content you produce:
+
+- **Avoid gerunds** — Don't use -ing verb forms where they obscure who performs the action. Write "When you work with LLMs..." instead of "When working with LLMs...". Write "Before you deploy the application..." instead of "Before deploying the application...".
+- **Lead with reasons** — Put the reason or purpose at the beginning of a sentence, not the end. Write "For better performance, cache and reuse the tokenizer" instead of "Cache and reuse the tokenizer for better performance". Write "To improve security, use HTTPS" instead of "Use HTTPS to improve security".
+
 ## Special Cases
 
 ### Breaking Changes

.github/instructions/Markdown.WritingStyle.instructions.md

@@ -22,6 +22,7 @@ NEVER use:
 - Jargon or overly complex technical language
 - Weak phrases like "you can" or "there is/are/were" unless they add value
 - "this" as a standalone pronoun — replace it with the specific noun it refers to (adjectival use before a noun, such as "this method", is fine)
+- Gerund phrases that obscure who performs an action (write "When you work with..." NOT "When working with..."; write "Before you deploy..." NOT "Before deploying...")
 
 ALWAYS:
 - Write like you speak using everyday words
@@ -36,6 +37,7 @@ ALWAYS:
 - Never place consecutive headings without content between them
 - Lead with the most important information first
 - Front-load keywords for scanning
+- Lead with the reason or purpose at the beginning of sentences, not the end (write "For better performance, cache the instance" NOT "Cache the instance for better performance"; write "To improve security, use HTTPS" NOT "Use HTTPS to improve security")
 
 ### Lists and Punctuation
 - **CRITICAL: Use Oxford comma in ALL lists (item1, item2, and item3) - NO EXCEPTIONS**