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

[Copilot]

Adds two mandatory style rules to all Copilot instruction files so generated and edited documentation is clearer and more scannable.

Rules added

• No gerunds as actor-obscuring phrases — "When working with..." → "When you work with..."
• Reason-first sentence structure — "Cache the instance for better performance" → "For better performance, cache the instance"

Files updated

• Markdown.WritingStyle.instructions.md — Gerund-avoidance added to NEVER use list; reason-first added to Headings and Content rules
• copilot-instructions.md — New ## Writing Style section with both rules and examples
• docseditor.agent.md — Gerund-conversion scan block added to Section 1 (VOICE AND TENSE); reason-first scan block added to Section 4 (SENTENCE STRUCTURE), with instruction to add a comma after the moved clause
• breakingchange.agent.md — Both rules added to the general instructions list

Original prompt

Update Copilot Instructions to Enforce Better Writing Style

Update all Copilot instructions, agents, and skills to require that Copilot itself uses these two principles when it creates or edits documentation and performs code reviews:

1. Copilot should avoid -ing words (gerunds) where possible in the content it generates - They lack clarity about who performs the action

   • ❌ Bad (what Copilot should NOT write): "When working with LLMs..."
   • ✅ Good (what Copilot SHOULD write): "When you work with LLMs..."

2. Copilot should put the reason at the beginning of sentences in the content it generates - Not at the end

   • ❌ Bad (what Copilot should NOT write): "Cache and reuse the tokenizer for better performance"
   • ✅ Good (what Copilot SHOULD write): "For better performance, cache and reuse the tokenizer"

Context

This is about the writing style we want Copilot to use when it:

• Creates or updates documentation
• Performs code reviews
• Suggests edits to Markdown files
• Generates new content

These are style rules that Copilot should apply to the content it produces, not necessarily how the instruction files themselves are written.

Files to Update

Update the following files to add these requirements to the style guidelines:

• .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 (if it contains writing style guidance)
• .github/skills/sort-redirects/SKILL.md (if it contains writing style guidance)

Where to Add These Rules

In copilot-instructions.md

Add a new section or enhance existing sections about writing style to include:

• Avoid gerunds (verbs ending in -ing) as the subject or in dependent clauses where clarity suffers
• Lead with reasons/purposes rather than ending sentences with them

In docseditor.agent.md

This file has extensive MANDATORY TRANSFORMATIONS sections. Add new rules to:

• Section 1 (VOICE AND TENSE): Add a subsection about avoiding gerunds
• Section 4 (SENTENCE STRUCTURE): Add a rule about leading with reasons/purposes

Example additions:

• "SCAN FOR AND CONVERT gerund phrases to clearer constructions:"

  • ❌ "When working with the API..." → ✅ "When you work with the API..."
  • ❌ "Before deploying the application..." → ✅ "Before you deploy the application..."

• "ALWAYS lead with reasons and purposes:"

  • ❌ "Cache the instance for better performance" → ✅ "For better performance, cache the instance"
  • ❌ "Use HTTPS to improve security" → ✅ "To improve security, use HTTPS"

In Markdown.WritingStyle.instructions.md

Under "## Voice and Tone Requirements" or "## Structure and Format Rules", add:

• Avoid gerunds in sentence construction where they create ambiguity about the actor
• Place reasons and purposes at the beginning of sentences

In agents/breakingchange.agent.md

If there are writing style requirements, add these two principles.

In skills files

Only add these rules if the skill files contain writing style guidance for generated content.

Goal

Make these two writing style principles part of the mandatory guidelines that Copilot must follow when it generates or edits documentation in this repository.

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.

User: @copilot Accepted Confirmation: Confirm agent session

Assistant: I've started working on updating the Copilot instructions to improve clarity by avoiding gerunds and leading with reasons. You can track the progress below:

data:
    - title: '[WIP] Update Copilot instructions for better clarity'
      repository: dotnet/docs
      url: https://github.com/copilot/tasks/pull/PR_kwDOAiOjoc7RQ_IM?session_id=00921f30-4b16-49ed-9896-40aacf0fc13b
      state: queued

The changes will:

• Replace gerund phrases (like "When working with...") with clearer constructions (like "When you work with...")
• Move reasons to the beginning of sentences for better clarity (like "For better performance, cache..." instead of "Cache... for better performance")
• Apply these pri...

This pull request was created from Copilot chat.

---

Internal previews

📄 File	🔗 Preview link
.github/agents/breakingchange.agent.md	"Breaking change: "
.github/agents/docseditor.agent.md	Article Writing and Editing Instructions for LLMs
.github/copilot-instructions.md	.github/copilot-instructions
.github/instructions/Markdown.WritingStyle.instructions.md	Markdown Writing Style Instructions

[Copilot]

Pull request overview

This PR updates the repository’s Copilot/agent instruction set to enforce two documentation-writing style rules: avoiding actor-obscuring “-ing” constructions (for example, “When you work with…”) and preferring reason-first sentences (for example, “For better performance, …”).

Changes:

• Adds a gerund/“-ing” avoidance rule to the shared Markdown writing-style instructions.
• Adds a new “Writing Style” section to .github/copilot-instructions.md describing both rules with examples.
• Extends docseditor and breakingchange agents with mandatory scan rules/examples for both patterns.

Reviewed changes

Copilot reviewed 4 out of 4 changed files in this pull request and generated 3 comments.

File	Description
.github/instructions/Markdown.WritingStyle.instructions.md	Adds “avoid actor-obscuring -ing phrases” and “reason-first” requirements to the general Markdown style rules.
.github/copilot-instructions.md	Introduces a dedicated Writing Style section documenting the two rules and examples.
.github/agents/docseditor.agent.md	Adds mandatory scan/convert blocks for -ing constructions and for moving purpose/reason clauses to the front.
.github/agents/breakingchange.agent.md	Adds both rules to the breaking-change agent’s global writing guidance.

[Copilot]

The instruction to move ANY trailing purpose/reason clause starting with "to", "for", or "so that" to the beginning is over-broad and can change meaning or produce incorrect rewrites (for example, many trailing "for " phrases are arguments/constraints, not purposes). Narrow this to clearly-identifiable purpose clauses (typically "to …" / "so that …"), and explicitly require preserving technical meaning when rewriting.

Suggested change

	- Look for ANY sentence that ends with a purpose or reason clause starting with "to", "for", or "so that", move it to the beginning, and add a comma after it
	- 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