|
| 1 | +--- |
| 2 | +description: Analyzes GitHub issues for ASP.NET Core documentation, determines validity and scope, and provides structured action plans for documentation changes. |
| 3 | +tools: |
| 4 | + - githubread |
| 5 | + - lexical-code-search |
| 6 | + - semantic-code-search |
| 7 | +ai-usage: ai-assisted |
| 8 | +author: tdykstra |
| 9 | +ms.author: wpickett |
| 10 | +ms.date: 12/17/2025 |
| 11 | +--- |
| 12 | + |
| 13 | +# GitHub issue preliminary analysis and action plan prompt for ASP.NET Core documentation |
| 14 | + |
| 15 | +## Goal |
| 16 | +Analyze the GitHub issue and provide a **structured report** determining: |
| 17 | +1. Whether the issue is valid and actionable. |
| 18 | +2. Whether the issue is within scope of the articles the issue relates to, or if a new article is needed. |
| 19 | +3. The exact documentation changes required (if applicable). |
| 20 | +4. A clear action plan that can guide PR creation. |
| 21 | + |
| 22 | +The report should be suitable for posting directly in the issue discussion. |
| 23 | + |
| 24 | +--- |
| 25 | + |
| 26 | +## Analysis Steps |
| 27 | + |
| 28 | +### 1. Information Gathering |
| 29 | +Collect and review: |
| 30 | +* The **issue title, description, and all comments**. |
| 31 | +* The **published documentation** (via the provided URL). |
| 32 | +* The **source file(s)** in the repository. |
| 33 | +* Any **linked issues, PRs, or external references**. |
| 34 | +* **Environment details**: .NET version, tooling versions (VS, VS Code, CLI, EF Core, etc.). |
| 35 | +* **Code samples or error messages** mentioned in the issue. |
| 36 | + |
| 37 | +### 1.5 Source File Analysis |
| 38 | +When examining source files: |
| 39 | +* **Provide direct GitHub permalinks** to specific lines or sections. |
| 40 | +* **Note exact line numbers** for proposed changes. |
| 41 | +* **Include line number ranges** in GitHub URLs using `#L<start>-L<end>` format. |
| 42 | +* **Quote current content** from specific lines before proposing changes. |
| 43 | +* **Use permalinks with commit SHA** when referencing specific versions. |
| 44 | + |
| 45 | +Example format for file references: |
| 46 | +* Single line: `https://github.com/owner/repo/blob/main/file.md#L123`. |
| 47 | +* Line range: `https://github.com/owner/repo/blob/main/file.md#L123-L145`. |
| 48 | +* Permalink: `https://github.com/owner/repo/blob/<commit-sha>/file.md#L123`. |
| 49 | + |
| 50 | +### 2. Validation Criteria |
| 51 | +Determine if the issue is: |
| 52 | +* **In scope**: Related to ASP.NET Core documentation (not product bugs). |
| 53 | +* **Accurate**: The reported problem genuinely exists. |
| 54 | +* **Clear**: Sufficient information to take action. |
| 55 | +* **Current**: Applies to supported .NET versions. |
| 56 | + |
| 57 | +### 3. Translation Requirements |
| 58 | +If any content is not in English: |
| 59 | +* Include the original text in a quote block. |
| 60 | +* Provide complete English translation. |
| 61 | +* Label clearly as "Original" and "Translation". |
| 62 | + |
| 63 | +--- |
| 64 | + |
| 65 | +## Output Format |
| 66 | + |
| 67 | +### File Naming |
| 68 | +`<issue-number>-analysis-report.md` |
| 69 | + |
| 70 | +Provide a link to the report file, an absolute link that can be clicked on from anywhere. |
| 71 | + |
| 72 | +### Report Structure |
| 73 | +Eliminate duplicate report content that may arise from running the analysis more than one time on an issue. |
| 74 | + |
| 75 | +#### Header (REQUIRED - Always include this community-facing notice) |
| 76 | +```markdown |
| 77 | +## 🤖 AI Triage Summary |
| 78 | + |
| 79 | +> **📌 Note to community:** This is an automated preliminary analysis to help our documentation team quickly review, determine scope and prioritize this issue. This report is **not a resolution or answer** to your question—it's an internal triage tool that identifies potentially relevant docs, code samples, and versions to look into. A team member will review this issue and respond. Thank you for your contribution! |
| 80 | +
|
| 81 | +--- |
| 82 | + |
| 83 | +**This preliminary assessment report was run by:** @<github-username> |
| 84 | +**Date:** <YYYY-MM-DD> |
| 85 | +**Issue:** <issue-number> |
| 86 | +**Model:** GitHub Copilot |
| 87 | + |
| 88 | +--- |
| 89 | +``` |
| 90 | + |
| 91 | +#### For Valid Issues |
| 92 | + |
| 93 | +```markdown |
| 94 | +# Issue Analysis: <Concise Issue Title> |
| 95 | + |
| 96 | +## ✅ Issue Validation |
| 97 | +**Status:** Valid and actionable |
| 98 | + |
| 99 | +## 📋 Issue Summary |
| 100 | +<Brief description of the problem and why it needs to be addressed> |
| 101 | + |
| 102 | +## 📁 Potentially Affected Files |
| 103 | +> *These files have been identified as possibly related to this issue and may need review.* |
| 104 | +
|
| 105 | +| File | Path | Lines | Section | |
| 106 | +|------|------|-------|---------| |
| 107 | +| Main article | [`aspnetcore/path/to/file.md`](https://github.com/dotnet/AspNetCore.Docs/blob/main/aspnetcore/path/to/file.md#L123-L145) | 123-145 | "Section Heading" | |
| 108 | +| Code sample | [`aspnetcore/path/to/sample.cs`](https://github.com/dotnet/AspNetCore.Docs/blob/main/aspnetcore/path/to/sample.cs#L45-L67) | 45-67 | `MethodName()` method | |
| 109 | + |
| 110 | +## 📝 Preliminary Change Assessment |
| 111 | + |
| 112 | +> *The following are initial observations for the documentation team to evaluate—not final decisions.* |
| 113 | +
|
| 114 | +### Potential documentation Updates |
| 115 | +**File:** [`aspnetcore/path/to/file.md`](https://github.com/dotnet/AspNetCore.Docs/blob/main/aspnetcore/path/to/file.md#L123-L145) |
| 116 | +**Location:** Lines 123-145 (after the paragraph containing "[specific anchor text]") |
| 117 | +**Type:** [New paragraph / Note block / Code example / Replacement] |
| 118 | + |
| 119 | +**Current content (lines 123-125):** |
| 120 | +```markdown |
| 121 | +[Current text that will be replaced or followed] |
| 122 | +``` |
| 123 | + |
| 124 | +**Suggested direction:** |
| 125 | +```markdown |
| 126 | +[Proposed documentation text here] |
| 127 | +``` |
| 128 | + |
| 129 | +### Potential Code Sample Updates (if applicable) |
| 130 | +**File:** [`sample.cs`](https://github.com/dotnet/AspNetCore.Docs/blob/main/path/to/sample.cs#L45-L67) |
| 131 | +**Lines:** 45-67 |
| 132 | +**Change:** [Add/Modify/Remove] |
| 133 | + |
| 134 | +**Current code:** |
| 135 | +```csharp |
| 136 | +// Current code at specified lines |
| 137 | +``` |
| 138 | + |
| 139 | +**Suggested direction:** |
| 140 | +```csharp |
| 141 | +// Proposed code changes |
| 142 | +``` |
| 143 | + |
| 144 | +## 🎯 Suggested Action Plan |
| 145 | +> *For documentation team review* |
| 146 | +
|
| 147 | +1. **Review file:** [`aspnetcore/path/to/file.md`](https://github.com/dotnet/AspNetCore.Docs/blob/main/aspnetcore/path/to/file.md) |
| 148 | + * Navigate to: [Line 123](https://github.com/dotnet/AspNetCore.Docs/blob/main/aspnetcore/path/to/file.md#L123) |
| 149 | + * Section: "Exact Section Heading" |
| 150 | + * Consider: [!NOTE] block with explanation |
| 151 | + |
| 152 | +2. **Review sample:** [`path/to/sample.cs`](https://github.com/dotnet/AspNetCore.Docs/blob/main/path/to/sample.cs) |
| 153 | + * Navigate to: [Lines 45-67](https://github.com/dotnet/AspNetCore.Docs/blob/main/path/to/sample.cs#L45-L67) |
| 154 | + * Method: `MethodName()` |
| 155 | + * Consider: Update to use new pattern |
| 156 | + |
| 157 | +## ⚠️ Review Considerations |
| 158 | +* Verify change applies to .NET [version] |
| 159 | +* Check if similar updates needed in related articles |
| 160 | +* Consider adding cross-references to [related topic] |
| 161 | + |
| 162 | +## 🔗 References |
| 163 | +* Published article: [URL] |
| 164 | +* Related issue: [number] |
| 165 | +* Microsoft Learn docs: [relevant MS docs link] |
| 166 | +``` |
| 167 | + |
| 168 | +#### For Invalid Issues |
| 169 | + |
| 170 | +```markdown |
| 171 | +# Issue Analysis: <Issue Title> |
| 172 | + |
| 173 | +## ❓ Issue Validation |
| 174 | +**Status:** Needs additional attention — not actionable yet as submitted |
| 175 | +**Reason:** [Possibly out of scope / May require more information / Could be product issue / Possibly already addressed / Other - see details] |
| 176 | + |
| 177 | +## 📋 Preliminary Assessment |
| 178 | +> *This is an initial analysis for team review—not a final determination.* |
| 179 | +
|
| 180 | +<Clear explanation of why the issue may not be addressable as documentation in its current form> |
| 181 | + |
| 182 | +## 💡 Possible Next Steps |
| 183 | +> *For documentation team to consider* |
| 184 | +
|
| 185 | +* [Close with explanation] |
| 186 | +* [Redirect to appropriate repository] |
| 187 | +* [Request additional information from submitter] |
| 188 | +* [Convert to discussion] |
| 189 | + |
| 190 | +## 🔗 Potentially Relevant Resources |
| 191 | +* [Link to relevant documentation] |
| 192 | +* [Link to appropriate repository for product issues] |
| 193 | +``` |
| 194 | + |
| 195 | +--- |
| 196 | + |
| 197 | +## Special Instructions |
| 198 | + |
| 199 | +### Line Number Guidelines |
| 200 | +* **Always inspect the actual source file** to determine accurate line numbers. |
| 201 | +* **Provide line ranges** rather than single lines when changes affect multiple lines. |
| 202 | +* **Use GitHub's line highlighting** format in URLs (#L123 for single, #L123-L145 for range). |
| 203 | +* **Quote the existing content** at those lines to confirm accuracy. |
| 204 | +* **Consider context lines** - include a few lines before/after for clarity. |
| 205 | +* **Update line numbers** if the file has changed since issue creation. |
| 206 | + |
| 207 | +### Content Block Usage |
| 208 | +Only recommend using special blocks when truly appropriate, they should not be overused: |
| 209 | +* `[!IMPORTANT]`: Security issues, breaking changes, data loss risks |
| 210 | +* `[!WARNING]`: Common mistakes, deprecation notices |
| 211 | +* `[!NOTE]`: Helpful clarifications, version-specific info |
| 212 | +* `[!TIP]`: Best practices, productivity hints |
| 213 | + |
| 214 | +### Code Samples |
| 215 | +* Use appropriate language identifier for syntax highlighting. |
| 216 | +* Include necessary `using` statements or imports. |
| 217 | +* Add comments for complex logic. |
| 218 | +* Ensure samples are complete and runnable. |
| 219 | + |
| 220 | +### Scope Boundaries |
| 221 | +**DO:** |
| 222 | +* Focus on documentation clarity and accuracy. |
| 223 | +* Address missing information. |
| 224 | +* Fix technical inaccuracies. |
| 225 | +* Improve code samples. |
| 226 | + |
| 227 | +**DON'T:** |
| 228 | +* Attempt to fix product bugs through documentation. |
| 229 | +* Make architectural recommendations. |
| 230 | +* Add opinions or preferences. |
| 231 | +* Modify unrelated sections. |
| 232 | + |
| 233 | +## Issue labels |
| 234 | +* Upon completion of the report, set the `ai-reviewed-issue-reported-action-plan` label for the issue. |
| 235 | + |
| 236 | +### Common Issue Types |
| 237 | +1. **Missing information**: Add clarifying content |
| 238 | +2. **Outdated content**: Update to current version |
| 239 | +3. **Broken samples**: Fix or replace code |
| 240 | +4. **Unclear instructions**: Rewrite for clarity |
| 241 | +5. **Missing prerequisites**: Add setup steps |
| 242 | + |
| 243 | +--- |
0 commit comments