Update Copilot instructions: eliminate gerunds, lead sentences with reasons

[Copilot]

Two style principles were inconsistently applied across all Copilot instruction files: gerund phrases obscure the actor ("When adapting..." vs. "When you adapt..."), and burying the reason at the end of a sentence reduces scannability ("Cache X for better performance" vs. "For better performance, cache X").

Changes by file

• copilot-instructions.md — Five fixes: "When reviewing/using/adapting/assigned" → explicit-subject forms; code comments guidance restructured to lead with the reason
• docseditor.agent.md — "Before writing" → "Before you write"; "When editing" → "When you edit"; the ✅ example for comma-in-introductory-phrase also updated to drop the gerund
• Markdown.WritingStyle.instructions.md — Opening sentence: "When writing or editing" → "When you write or edit"
• redirect-article/SKILL.md — Opening sentence restructured to lead with purpose; all four "When to Use" bullets converted from gerund fragments to imperative verbs
• sort-redirects/SKILL.md — Opening sentence restructured to lead with purpose

Original prompt

Update Copilot Instructions for Better Clarity

Update all Copilot instructions, agents, and skills to follow these two principles:

1. Avoid -ing words (gerunds) where possible - They lack clarity about who performs the action

   • ❌ Bad: "When working with LLMs..."
   • ✅ Good: "When you work with LLMs..."

2. Put the reason at the beginning of the sentence - Not at the end

   • ❌ Bad: "Cache and reuse the tokenizer for better performance"
   • ✅ Good: "For better performance, cache and reuse the tokenizer"

Files to Update

Update the following files:

• .github/copilot-instructions.md
• .github/agents/breakingchange.agent.md
• .github/agents/docseditor.agent.md
• .github/instructions/Markdown.WritingStyle.instructions.md
• .github/skills/redirect-article/SKILL.md
• .github/skills/sort-redirects/SKILL.md

Specific Examples to Fix

In copilot-instructions.md:

• Line 17: "When using an IDE with a human guiding AI:" → "When you use an IDE with a human to guide AI:"
• Line 54: "When you add code, use code comments sparingly because they don't get localized." → "Because code comments don't get localized, use them sparingly when you add code."
• Line 76: "When adapting content from external sources like blog posts into documentation:" → "When you adapt content from external sources like blog posts into documentation:"

In breakingchange.agent.md:

• Line 104: "When assigned an issue or directly given a task in GitHub:" → "When you're assigned an issue or directly given a task in GitHub:"

In docseditor.agent.md:

• Line 27: "Before writing, ask the user for a template" → "Before you write, ask the user for a template"
• Line 59: "When editing, focus on these areas" → "When you edit, focus on these areas"
• Line 169: "When replacing Newtonsoft the plan switches..." → "When replacing Newtonsoft, the plan switches..." (also add comma)

In Markdown.WritingStyle.instructions.md:

• Line 7: "When writing or editing Markdown documentation, follow these style guidelines:" → "When you write or edit Markdown documentation, follow these style guidelines:"

In redirect-article/SKILL.md:

• Line 7: "Delete a markdown article from the repository and create a redirect entry that points users to a different article. This ensures existing links and bookmarks continue to work after content is reorganized." → "To ensure existing links and bookmarks continue to work after content is reorganized, delete a markdown article from the repository and create a redirect entry that points users to a different article."
• Line 15: "Removing outdated content while preserving URL functionality" → "Remove outdated content while you preserve URL functionality"

In sort-redirects/SKILL.md:

• Line 7: "Sort redirect entries in Open Publishing redirection JSON files alphabetically by path. This ensures consistency and makes the redirect files easier to maintain." → "To ensure consistency and make the redirect files easier to maintain, sort redirect entries in Open Publishing redirection JSON files alphabetically by path."

General Guidance

Apply these principles consistently throughout all files. Look for:

• Gerund phrases starting sentences or clauses (especially "When [verb]ing...")
• Sentences that end with reasons/purposes (often containing "to [verb]" or "for [reason]")
• Instructions that lack clarity about the actor

Transform them to be clearer and more direct.

The following is the prior conversation context from the user's chat exploration (may be truncated):

User: Please update the Copilot instructions/agents/skills to avoid the use of -ing words where possible (it lacks clarity about who is doing the thing). For example, use "When you work with LLMs..." instead of "When working with LLMs...".

Also, the reason to take an action should be at the beginning of the sentence, not the end. For example, "For better performance, cache and reuse the instance" instead of "Cache and reuse the tokenizer for better performance".

Assistant: Now I'll create a PR to update these files to avoid -ing words and put reasons at the beginning of sentences.

Assistant: I'm waiting for your response to continue with creating the pull request that will update the Copilot instructions to avoid gerunds and lead with reasons.

This pull request was created from Copilot chat.