From 9dd8edb1a9999ea65c50864dae20c16d0f49a876 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Tue, 24 Mar 2026 19:46:03 +0000 Subject: [PATCH 1/8] Initial plan From cc2ad554553b84be5680e524944b8c330722b940 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Tue, 24 Mar 2026 19:49:06 +0000 Subject: [PATCH 2/8] Add article-freshness-review prompt file Co-authored-by: wadepickett <10985336+wadepickett@users.noreply.github.com> Agent-Logs-Url: https://github.com/dotnet/AspNetCore.Docs/sessions/bffb0b74-2d76-417a-be74-7198e4a8f0cd --- .../article-freshness-review.prompt.md | 112 ++++++++++++++++++ 1 file changed, 112 insertions(+) create mode 100644 .github/prompts/article-freshness-review.prompt.md diff --git a/.github/prompts/article-freshness-review.prompt.md b/.github/prompts/article-freshness-review.prompt.md new file mode 100644 index 000000000000..7283cf177853 --- /dev/null +++ b/.github/prompts/article-freshness-review.prompt.md @@ -0,0 +1,112 @@ +--- +description: "Generates a freshness review report for an ASP.NET Core documentation article. Attach this prompt in Copilot Chat, then provide the article URL. The report is for posting in issue discussions — it does NOT create a PR." +--- + +# ASP.NET Core Article Freshness Review + +> **Usage**: Attach this prompt file in Copilot Chat, then type the article URL +> (e.g., `Review https://learn.microsoft.com/aspnet/core/web-api/action-return-types`). +> Paste the resulting report into the GitHub issue discussion. +> **This prompt does NOT create a PR or modify any files.** + +## Instructions + +You are reviewing an ASP.NET Core documentation article for freshness and accuracy. + +### Step 1: Load Context + +Read the repository's copilot instruction file for conventions and rules: +[copilot-instructions.md](../copilot-instructions.md) + +And read the dotnet/docs repository editing instructions: +https://raw.githubusercontent.com/dotnet/docs/refs/heads/main/.github/agents/docseditor.agent.md + +### Step 2: Review the Article + +Review the article provided by the user. + +Evaluate it against ALL of the following criteria: + +**A. Moniker Range & Versioning** +* Are there newer APIs, packages, or approaches that supersede what the article describes? +* If so: Is the monikerRange in the frontmatter still appropriate? +* If the article covers a version that is no longer the latest, does it include guidance directing readers to the current version's documentation? + +**B. Frontmatter & Metadata** +* Is ms.date in MM/DD/YYYY format? +* Is the title field listed first, with remaining fields in alphabetical order? +* Are all required metadata fields present? + +**C. Content Accuracy** +* Are code samples correct for the targeted framework version(s)? +* Are NuGet package names and namespaces still valid? +* Are referenced APIs still available and not deprecated in the targeted version? +* Do xref links (xref:) resolve to valid UIDs? + +**D. Style & Conventions (per copilot-instructions.md)** +* Placeholders in code/commands use {UPPER CASE WITH SPACES} format with descriptions in surrounding text. +* Section headers do NOT end with periods. +* Bullet markers use * (not -). +* Links follow the documented conventions (relative for MS Learn, full URL for external). +* Code blocks use :::code snippet references where appropriate. + +**E. External Links** +* Are external URLs likely still valid? (Flag any that point to known-sunset services or archived repos.) + +### Step 3: Produce the Report + +Output a single Markdown report with this EXACT structure: + +``` +# Freshness Review Report + +**File:** `{FILE PATH}` +**Repository:** `dotnet/AspNetCore.Docs` +**Reviewed:** {REVIEW DATE} +**Reviewer:** @{REVIEWER} +**Article URL:** {ARTICLE URL} +**Source URL:** {SOURCE URL} + +--- + +## Verdict: **{Needs Updating | Current — No Changes Needed}** + +A verdict of "Needs Updating" requires at least one Critical or Moderate issue. + +--- + +## Critical Issues + +{Issues that affect correctness, reader confusion, or discoverability. +Each issue should include: +- **Issue title** +- **Location:** file path and line number(s) +- **Current content:** (quoted) +- **Recommended fix:** (exact replacement text) +- **Rationale:** why this matters} + +## Moderate Issues + +{Issues that affect style compliance or minor accuracy. +Same sub-structure as Critical.} + +## Minor Issues + +{Cosmetic or convention-based issues. +Same sub-structure as Critical.} + +--- + +## Summary of Recommended Changes + +{A numbered checklist of ALL changes, in order of priority, that can be +used directly as a task list for the PR author.} +``` + +## Rules + +* Do NOT invent issues. If something is correct, say so. +* Do NOT suggest changes outside the scope of the copilot-instructions.md rules and current ASP.NET Core documentation standards. +* If recommending a NOTE or callout, provide the EXACT Markdown to insert including moniker-range fencing if applicable. +* Flag the issue title if it doesn't match the actual file name or path. +* Every recommended change must include the exact "before" and "after" text. From 18c0894826744cb719548fad052f2f1e12d4af42 Mon Sep 17 00:00:00 2001 From: Wade Pickett Date: Tue, 24 Mar 2026 13:03:40 -0700 Subject: [PATCH 3/8] Revise description for article freshness review prompt Updated the description for the article freshness review prompt to provide clearer usage instructions. --- .github/prompts/article-freshness-review.prompt.md | 7 ++++++- 1 file changed, 6 insertions(+), 1 deletion(-) diff --git a/.github/prompts/article-freshness-review.prompt.md b/.github/prompts/article-freshness-review.prompt.md index 7283cf177853..968f21e96f29 100644 --- a/.github/prompts/article-freshness-review.prompt.md +++ b/.github/prompts/article-freshness-review.prompt.md @@ -1,5 +1,10 @@ --- -description: "Generates a freshness review report for an ASP.NET Core documentation article. Attach this prompt in Copilot Chat, then provide the article URL. The report is for posting in issue discussions — it does NOT create a PR." +description: > + Generates a freshness review report for an ASP.NET Core doc article. + Usage: Open a GitHub issue, open Copilot Chat, and paste: + "Read and follow all instructions in .github/prompts/article-freshness-review.prompt.md. + Use this issue as context. Generate the freshness review report." + Then copy the report into the issue discussion. Does NOT create a PR. --- # ASP.NET Core Article Freshness Review From 8e5a73b0b1747ba07cf3bc3af9fab62751a5c09f Mon Sep 17 00:00:00 2001 From: Wade Pickett Date: Tue, 24 Mar 2026 13:05:28 -0700 Subject: [PATCH 4/8] Update article-freshness-review prompt metadata Added author and metadata for freshness review prompt. --- .github/prompts/article-freshness-review.prompt.md | 3 +++ 1 file changed, 3 insertions(+) diff --git a/.github/prompts/article-freshness-review.prompt.md b/.github/prompts/article-freshness-review.prompt.md index 968f21e96f29..eea6812e3a07 100644 --- a/.github/prompts/article-freshness-review.prompt.md +++ b/.github/prompts/article-freshness-review.prompt.md @@ -1,10 +1,13 @@ --- +author: wpickett description: > Generates a freshness review report for an ASP.NET Core doc article. Usage: Open a GitHub issue, open Copilot Chat, and paste: "Read and follow all instructions in .github/prompts/article-freshness-review.prompt.md. Use this issue as context. Generate the freshness review report." Then copy the report into the issue discussion. Does NOT create a PR. +ms.author: wpickett +ms.date: 03/24/2026 --- # ASP.NET Core Article Freshness Review From b6eb1b3c6d64169a1e9284422dac95c3d6ae9a13 Mon Sep 17 00:00:00 2001 From: Wade Pickett Date: Tue, 24 Mar 2026 13:36:34 -0700 Subject: [PATCH 5/8] Add Copilot Feasibility Assessment section Added a feasibility assessment section for Copilot handling of freshness updates, including justification and recommendations. --- .../prompts/article-freshness-review.prompt.md | 18 ++++++++++++++++++ 1 file changed, 18 insertions(+) diff --git a/.github/prompts/article-freshness-review.prompt.md b/.github/prompts/article-freshness-review.prompt.md index eea6812e3a07..5fc264609b1d 100644 --- a/.github/prompts/article-freshness-review.prompt.md +++ b/.github/prompts/article-freshness-review.prompt.md @@ -105,6 +105,24 @@ Same sub-structure as Critical.} --- +## Copilot Feasibility Assessment + +**Can Copilot handle this freshness update?** {Yes | Likely | Partial | No} + +**Justification:** +{Explain why Copilot can or cannot be expected to handle the full update +correctly with minimal PR review corrections. Consider: +* Are the changes primarily mechanical (metadata, formatting, link fixes)? +* Do any changes require deep domain knowledge of ASP.NET Core APIs or architecture? +* Are there judgment calls about content restructuring or technical accuracy? +* Would the update require testing code samples against a running application?} + +**Recommendation:** +{One of: +* "Assign to Copilot" — Changes are mechanical and well-defined +* "Assign to Copilot with human review of [specific areas]" — Mostly mechanical but some areas need expert judgment +* "Assign to a human author" — Changes require domain expertise, significant rewriting, or code verification that Copilot cannot reliably perform} + ## Summary of Recommended Changes {A numbered checklist of ALL changes, in order of priority, that can be From 1bcde40b5f50059fad277fadb823cdfc9beb26d9 Mon Sep 17 00:00:00 2001 From: Wade Pickett Date: Tue, 24 Mar 2026 14:32:59 -0700 Subject: [PATCH 6/8] Update metadata field check instructions Clarified the check for required metadata fields in the article freshness review prompt. --- .github/prompts/article-freshness-review.prompt.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/.github/prompts/article-freshness-review.prompt.md b/.github/prompts/article-freshness-review.prompt.md index 5fc264609b1d..924d1ac41e09 100644 --- a/.github/prompts/article-freshness-review.prompt.md +++ b/.github/prompts/article-freshness-review.prompt.md @@ -43,7 +43,9 @@ Evaluate it against ALL of the following criteria: **B. Frontmatter & Metadata** * Is ms.date in MM/DD/YYYY format? * Is the title field listed first, with remaining fields in alphabetical order? -* Are all required metadata fields present? +* Are all required metadata fields present? (Check only for presence, not for + cross-field value consistency. For example: The `author` and `ms.author` fields are + independent and are not required to match.) **C. Content Accuracy** * Are code samples correct for the targeted framework version(s)? From 9aacb6ebaeae272e0b3c81dce50aa7d603d89c6b Mon Sep 17 00:00:00 2001 From: Wade Pickett Date: Tue, 24 Mar 2026 14:53:11 -0700 Subject: [PATCH 7/8] Update article freshness review prompt Added guidance for flagging old ms.date as Minor update. --- .github/prompts/article-freshness-review.prompt.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/.github/prompts/article-freshness-review.prompt.md b/.github/prompts/article-freshness-review.prompt.md index 924d1ac41e09..88a328041b8f 100644 --- a/.github/prompts/article-freshness-review.prompt.md +++ b/.github/prompts/article-freshness-review.prompt.md @@ -42,6 +42,10 @@ Evaluate it against ALL of the following criteria: **B. Frontmatter & Metadata** * Is ms.date in MM/DD/YYYY format? +* If ms.date is older than 6 months, flag it as a Minor metadata-only update. + An old ms.date does NOT by itself indicate the article content is stale — the + content may still be accurate and current. Classify a stale ms.date as Minor + severity. It must never contribute to a "Needs Updating" verdict on its own. * Is the title field listed first, with remaining fields in alphabetical order? * Are all required metadata fields present? (Check only for presence, not for cross-field value consistency. For example: The `author` and `ms.author` fields are From a62c2936859d103016f462ed39509962d4e36b29 Mon Sep 17 00:00:00 2001 From: Wade Pickett Date: Tue, 24 Mar 2026 15:02:23 -0700 Subject: [PATCH 8/8] Apply suggestions from code review Since tdykstra has added signficant suggestions for improvement, adding him to the author frontmatter value. Co-authored-by: Wade Pickett --- .github/prompts/article-freshness-review.prompt.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/prompts/article-freshness-review.prompt.md b/.github/prompts/article-freshness-review.prompt.md index 88a328041b8f..003c0e95011e 100644 --- a/.github/prompts/article-freshness-review.prompt.md +++ b/.github/prompts/article-freshness-review.prompt.md @@ -1,5 +1,5 @@ --- -author: wpickett +author: tdykstra description: > Generates a freshness review report for an ASP.NET Core doc article. Usage: Open a GitHub issue, open Copilot Chat, and paste: