Copilot-instructions.md improvements: Intro, ms.date and instructions for copilot itself (wadepickett)

[wadepickett]

Watching the results of the GitHub Copilot agent handling issues with its own PR's, the following rules should be addressed and tested in AspNetCore.Docs/.github/copilot-instructions.md at main · dotnet/AspNetCore.Docs

I am batching the issue/solutions we ran into for the sprint here so as a team we can review and reconsider the architecture of the instructions and details in it.

---

Problem: Copilot often does not read through the issue discussion and just acts on the issue description. So it misses all further issue analysis and recommended action.
See:
#35484 (Issue assigned to copilot after updates including issue analysis and recommended action in the issue description)
#36121 (Copilot fails to read the issue discussion)
#36122 (Copilot finally reads the issue discussion and produces he correct PR changes.)
Solution, add this instruction:

### Issue Discussion Analysis
When working on an issue:
1. **Read the complete issue discussion** - Don't rely solely on the initial issue description
2. **Prioritize maintainer guidance** - Comments from repository maintainers (especially those with "MEMBER" association) should take precedence over the original issue description
3. **Look for updated analysis** - Later comments may contain revised understanding, additional context, or modified resolution approaches
4. **Check for explicit instructions** - Look for phrases like "Action required by GitHub Copilot" or direct "@copilot" mentions that provide specific guidance
5. **Validate your understanding** - If the discussion seems to contradict the initial issue description, follow the most recent maintainer guidance

---

Github copilot sometimes neglects to put the Issue number its created PR fixes in the its PR description. Add that to the checklist instructions so it no longer skips that on occasion. This seems to happen with more processing heavy issues it is assigned.

---

Code snippet syntax:
Copilot uses the existing old snippet syntax if it run into it on an existing topic and code. It needs the updated syntax to use in all cases:
See an example of this problem: #36101 (comment)

Copilot PR Success Checklist

Use this checklist for every PR to ensure first-commit success and avoid common mistakes:

1. PR Description Requirements

• ALWAYS include "Fixes #[issue-number]" in the PR description to link back to the original issue
• Include a clear summary of changes made
• List all files that were modified with brief descriptions

2. Metadata and Date Requirements

• CRITICAL: Set ms.date to the actual current date in MM/DD/YYYY format (GitHub Copilot often uses incorrect future dates)
• Add ai-usage: ai-assisted metadata if any AI assistance was used
• Place title metadata first, followed by remaining metadata in alphabetical order
• Update ms.date if more than 50 characters are changed in existing files

3. Code Snippets - Triple-Colon Syntax Requirements

• NEVER use [!code-csharp[]] syntax - this is incorrect and will cause build errors
• ALWAYS use triple-colon syntax: :::code language="csharp" source="path" id="snippet_name" highlight="lines":::
• NEVER use name="snippet_name" attribute - this is unsupported and causes build errors
• ALWAYS use id="snippet_name" to reference named snippets
• Use highlight="3-5,9" for line highlighting (relative to snippet content, not absolute file line numbers)
• Example of correct syntax:

  :::code language="csharp" source="~/path/to/file.cs" id="snippet_policy" highlight="3-5,9":::

4. Code Snippet Folder Structure Requirements

• For code snippets longer than 6 lines, create proper folder structure:
  • article-name/snippets/version/filename.cs (e.g., cookie/snippets/6.0/Program.cs)
• Create version-specific subfolders: 3.x, 6.0, 8.0, 9.0, etc.
• Use file-relative paths for snippets in same article folder
• Use repository root-relative paths (~/) for shared snippets

5. Code Snippet Markers in .cs Files - CRITICAL

• NEVER use #region snippet_name and #endregion syntax in .cs files
• ALWAYS use // <snippet_name> and // </snippet_name> format (all lowercase)
• Examples of correct .cs file snippet markers:

  // <snippet_policy>
  var cookiePolicyOptions = new CookiePolicyOptions
  {
      MinimumSameSitePolicy = SameSiteMode.Strict,
  };
  app.UseCookiePolicy(cookiePolicyOptions);
  // </snippet_policy>

• INCORRECT format to avoid:

  #region snippet_policy
  // code here
  #endregion

6. Code Comments and Localization

• NEVER add explanatory code comments like // Configure cookie policy options in .cs snippet files
• NEVER add comments like // Add Cookie Policy Middleware - these prevent proper localization
• Rely on markdown prose before/after code snippets for explanations instead of inline comments
• Only keep comments that are essential to the code's functionality

7. Build Validation Requirements

• ALWAYS validate code snippet syntax by checking build logs for errors
• Watch for "unexpected attribute" errors indicating incorrect syntax usage
• Test that snippet references resolve correctly (no broken id references)
• Verify that highlight line numbers are relative to snippet content, not absolute file lines

8. Common Syntax Errors to Avoid

• Using range="5-10" instead of id="snippet_name"
• Using name="snippet_name" instead of id="snippet_name"
• Mixing old [!code-csharp[]] syntax with new triple-colon syntax
• Using absolute line numbers in highlight="" instead of relative to snippet
• Using #region/#endregion in .cs files instead of // <snippet_name> format

9. Version-Specific Considerations

• Create separate snippet files for different .NET versions (3.x, 6.0, 8.0, 9.0+)
• Ensure examples use appropriate syntax for the target version
• Reference the correct version-specific snippet file in markdown

10. Final Validation Checklist

• Verify all triple-colon code references use correct id="" syntax
• Confirm all .cs files use // <snippet_name> markers (never #region)
• Check that no explanatory comments were added to .cs files
• Validate ms.date is set to actual current date (not a future date)
• Ensure "Fixes #[issue-number]" is in PR description
• Test build passes without warnings related to your changes

Note: These issues frequently recur due to GitHub Copilot's tendency to use outdated or incorrect syntax patterns. Following this checklist systematically will prevent the iterative correction cycles seen in issue #35782.

Add a "Pre-Completion Compliance Checklist" section at the top of the copilot-instructions.md file that consolidates the most critical requirements.

Why: This would create a fail-safe checklist that's impossible to miss, while keeping the detailed explanations in their current locations for reference. GitHub Copilot was skipping much of the rules in the copilot-intructions.md as it became preoccupied with new article creation. See rerlated GitHub Copilot PR discussion here: #36015 (comment)

Example checklist:

Pre-Completion Compliance Checklist

Before marking any PR as complete, verify ALL of the following:

Required Frontmatter (for any new/updated .md files):

• title: metadata (first line)
• ai-usage: ai-assisted if AI was used
• Metadata in alphabetical order after title
• ms.date: MM/DD/YYYY updated if >50 characters changed

Code Standards:

• C# code uses 4-space indentation
• Language codes match the standards table (lines 135-146)

Content Standards:

• Use xref syntax for internal links: <xref:target-uid>
• Use backticks for code elements in text
• Follow sentence case for headers

---

Related to @tdykstra copilot issue assignment test #35989

Introductory paragraph

• When drafting the first paragraph of any new article, or when significantly updating an existing article:
  • Explain why and when the topic matters in practical ASP.NET Core development scenarios.
  • Give a concise summary of what the article covers or enables, so readers know what to expect.
  • When significantly updating, revise the introductory paragraph to match the new scope and content.

---

ms.date metadata

• Always use ms.date: <today's date> in the format MM/DD/YYYY.

  • MM: Two digits, leading zero if needed (01-12)
  • DD: Two digits, leading zero if needed (01-31)
  • YYYY: Four digits
  • Example: ms.date: 08/25/2025
  • Incorrect: ms.date: 8/25/2025 (missing leading zero)

• If the file already has an ms.date value and your changes affect more than 50 characters, update ms.date to today's date.

  • Only update if net change is more than 50 characters.

NOTE:
I should consider changing the current 50-character rule with:

• For any new or updated .md file, update the ms.date metadata to today's date if you've made substantial content changes (moved sections, removed/added significant content blocks, or restructured the document).

This eliminates the need for character counting and focuses on meaningful content changes that warrant a date update, making the decision process much faster while still capturing significant updates. Copilot was spending way too much processing time and steps to determine if the 50 character threshold had been achieved.

Also it needs a note to always use what the current system date. If it sees the doc is really old, it can decide the system date must not be accurate and chooses a date inline with the last commit on the file. See PR #35986 for an example of this .
Example where Copilot ignores the system date when it should not:

Also, here are recommendations from GitHub Copilot on what it thought it needed to handle the ms.date info and to stop missing it: ( see: #36109 (comment) )

Why it was missed:
The ms.date instruction is buried deep in the copilot instructions (line 79) within a subsection about frontmatter metadata. While reviewing my changes, I focused on the primary task (adding Swagger tabs) and didn't systematically check all metadata requirements.

Suggestions to improve copilot-instructions.md:

Create a dedicated "Post-Change Checklist" section with prominent visibility:

Post-Change Checklist

After making any changes to .md files, always verify:

• If >50 characters changed: Update ms.date to current date (MM/DD/YYYY format)
• Add ai-usage: ai-assisted if AI was used
• Metadata is in alphabetical order after title
  Move critical metadata rules earlier in the document, closer to the top where they're more likely to be noticed during task planning.

Add emphasis formatting to make the 50-character rule more prominent:

• CRITICAL: Metadata ms.date: <today's date> with a format of MM/DD/YYYY. If the file already has a ms.date metadata, update it to today's date if more than 50 characters are changed in the file.
  Fixed in commit 414d1a3.

---

Changes for PR description:

• Put the Issue number for the issue the PR addresses at the top of the PR description in the format Fixes #[Issue Number]

---

We can use GitHub Copilot to help improve its own copilot-instructions.md document based on feedback from issues it has handled and PRs it has created. After testing this approach, I've found that Copilot needs explicit guidance for this self-improvement workflow.

I recommend adding the following rules near the top of the copilot-instructions.md file:

Writing instructions for copilot-instructions.md

• Write instructions specifically for GitHub Copilot to follow, not for a general audience.
• Use clear, direct, and actionable language so Copilot can interpret and apply the instructions without ambiguity.
• Avoid explanations, background info, or conversational tone intended for a general audience. Only provide what GitHub Copilot needs to be effective.
• Match the formatting and structure of existing sections in copilot-instructions.md.
• Use bullet points or numbered steps for clarity when appropriate.
• Place each instruction in the most relevant subsection based on its topic (e.g., metadata, article structure, code formatting). Create new sections or subsections as needed.

---

Associated WorkItem - 483885

[wadepickett]

cc: @tdykstra