Agents | Add Azure DevOps work item markdown formatting guide

.github/instructions/ado-work-items-markdown.instructions.md

@@ -0,0 +1,135 @@
+---
+applyTo: "**"
+---
+# Azure DevOps Work Items: Markdown Description Rules
+
+Use this guide whenever creating or updating Azure DevOps work items that include rich text in `System.Description`.
+
+## Goals
+
+- Ensure descriptions render as Markdown (not HTML/plain text)
+- Preserve newline characters and list structure
+- Verify work items after every batch update
+
+## Required Behavior
+
+1. Always use `az rest` for description content-type changes.
+2. Use `application/json-patch+json` for PATCH requests.
+3. Set `multilineFieldsFormat.System.Description` to `markdown`.
+4. Preserve exact newlines in the Markdown body.
+5. Verify both format and newline integrity after updates.
+
+## Authentication and Resource
+
+Use Azure DevOps resource audience when calling `az rest`:
+
+- Resource: `499b84ac-1321-427f-aa17-267ca6975798`
+
+Example auth check:
+
+```bash
+az rest \
+  --method GET \
+  --resource 499b84ac-1321-427f-aa17-267ca6975798 \
+  --url "https://dev.azure.com/<org>/_apis/projects?api-version=7.1-preview.4"
+```
+
+Note: API versions can differ by endpoint. The examples below use `7.1-preview.3` for work item PATCH calls, while this auth check uses `7.1-preview.4`.
+
+## Safe Update Pattern (Prevents Type/Value Errors)
+
+Some work items reject a direct type switch unless a valid value is provided. Use this two-step process:
+
+### Step 1: Capture current description
+
+```bash
+desc=$(az boards work-item show --id <id> | jq -r '.fields["System.Description"] // ""')
+```
+
+### Step 2: Force markdown type with temporary empty value
+
+```bash
+PATCH_STEP1_FILE="${PATCH_STEP1_FILE:-./patch-step1.json}"
+
+jq -n '[
+  {"op":"replace","path":"/fields/System.Description","value":""},
+  {"op":"replace","path":"/multilineFieldsFormat/System.Description","value":"markdown"}
+]' >"$PATCH_STEP1_FILE"
+
+az rest \
+  --method PATCH \
+  --resource 499b84ac-1321-427f-aa17-267ca6975798 \
+  --url "https://dev.azure.com/<org>/<project>/_apis/wit/workitems/<id>?api-version=7.1-preview.3" \
+  --headers "Content-Type=application/json-patch+json" \
+  --body @"$PATCH_STEP1_FILE"
+```
+
+### Step 3: Restore exact Markdown text
+
+```bash
+PATCH_STEP2_FILE="${PATCH_STEP2_FILE:-./patch-step2.json}"
+
+jq -n --arg d "$desc" '[
+  {"op":"replace","path":"/fields/System.Description","value":$d}
+]' >"$PATCH_STEP2_FILE"
+
+az rest \
+  --method PATCH \
+  --resource 499b84ac-1321-427f-aa17-267ca6975798 \
+  --url "https://dev.azure.com/<org>/<project>/_apis/wit/workitems/<id>?api-version=7.1-preview.3" \
+  --headers "Content-Type=application/json-patch+json" \
+  --body @"$PATCH_STEP2_FILE"
+```
+
+## Newline Integrity Checks
+
+After updates, confirm newline characters are still present and structure was not flattened.
+
+### Check format and description sample
+
+```bash
+az boards work-item show --id <id> | jq '.multilineFieldsFormat, .fields["System.Description"][0:200]'
+```
+
+Expected:
+
+- `multilineFieldsFormat.System.Description == "markdown"`
+- Description text contains `\n` where line breaks are expected
+
+### Check line count did not collapse
+
+```bash
+az boards work-item show --id <id> \
+| jq -r '.fields["System.Description"]' \
+| awk 'END { print NR }'
+```
+
+If a multi-line description unexpectedly returns `1`, newline content was likely lost.
+
+## Batch Verification Script
+
+Use this after bulk updates:
+
+```bash
+python3 - <<'PY'
+import json, subprocess
+ids = [12345, 12346]  # replace with your target IDs
+bad = []
+for i in ids:
+    out = subprocess.check_output(["az", "boards", "work-item", "show", "--id", str(i)], text=True)
+    j = json.loads(out)
+    fmt = (j.get("multilineFieldsFormat") or {}).get("System.Description")
+    desc = j.get("fields", {}).get("System.Description") or ""
+    if fmt != "markdown" or "\n" not in desc:
+        bad.append((i, fmt, "has_newlines" if "\n" in desc else "missing_newlines"))
+print("noncompliant:", len(bad))
+for row in bad:
+    print(row)
+PY
+```
+
+## Common Failure Modes
+
+- `401` or `TF400813`: wrong token audience or insufficient auth context
+- `Content-Type ... not supported`: must use `application/json-patch+json`
+- `type changed without a value`: use two-step pattern (empty + markdown type, then restore text)

.github/prompts/review-pr-feedback.prompt.md

@@ -0,0 +1,123 @@
+---
+name: review-pr-feedback
+description: Uses gh CLI to collect unresolved PR review feedback, optionally includes discussion comments, applies fixes, and reports status.
+argument-hint: pr=<number-or-url> repo=<owner/repo-optional> includeDiscussionComments=<true|false> authorFilter=<optional regex or csv> testScope=<optional test hint>
+tools: ['edit/editFiles', 'edit/createFile', 'read/readFile', 'read/problems', 'search/codebase', 'search/textSearch', 'search/fileSearch', 'execute/runInTerminal', 'execute/getTerminalOutput']
+---
+You are an expert software maintenance agent focused on resolving pull request feedback quickly, safely, and with clear traceability.
+
+## Context
+- Workspace root: ${workspaceFolder}
+- Target PR: ${input:pr}
+- Optional repository override: ${input:repo}
+- Include non-review discussion comments: ${input:includeDiscussionComments}
+- Optional author filter: ${input:authorFilter}
+- Optional focused testing hint: ${input:testScope}
+- Optional selected context: ${selection}
+
+## Skills
+#skill:generate-mstest-filter
+
+Use this skill when building a dotnet test filter:
+- [generate-mstest-filter](.github/skills/generate-mstest-filter/SKILL.md)
+
+Follow the referenced skill instructions before producing any custom filter.
+
+## Task
+1. Validate prerequisites
+- Confirm gh CLI is installed and authenticated.
+- Resolve repository from ${input:repo}, or infer from git remote.
+- Resolve PR number from ${input:pr} (accept number or URL).
+- Discover the correct git remote name from the current repository and store it for later commands.
+- Use that discovered remote name for push and any other git operations that require a remote; do not assume `origin`.
+
+2. Gather actionable review feedback
+- Query PR review threads with gh api GraphQL.
+- Keep only unresolved threads where isResolved is false.
+- Extract thread id, file path, line/startLine, comment url, author login, and body.
+- If ${input:authorFilter} is provided, apply it case-insensitively.
+
+3. Optionally gather non-review discussion comments
+- If ${input:includeDiscussionComments} is true, fetch PR issue comments.
+- Mark these as Informational because they do not have open/resolved state.
+- Apply ${input:authorFilter} if provided.
+
+4. Build an implementation plan
+- Group unresolved review feedback by file and risk.
+- Determine minimal safe edits needed.
+- Identify comments that are non-actionable or ambiguous.
+- Ask the user to confirm the plan before proceeding, showing a concise summary of proposed changes and rationale.
+
+5. Implement and verify
+- Apply required code or test updates with smallest safe change set.
+- Run targeted checks first.
+- If ${input:testScope} is provided, generate and use a focused MSTest filter via the skill.
+- Collect diagnostics when tests cannot run.
+
+6. Classify each item
+- Fixed: change implemented and validated.
+- Needs Clarification: ambiguous, conflicting, or insufficiently specified.
+- Blocked: external dependency, permission, or missing context.
+- Informational: non-review discussion comment captured only.
+
+7. Produce a final report
+- Keep review-thread outcomes and discussion outcomes in separate sections.
+- Include evidence for each item: file location, change summary, validation result.
+- Draft a distinct reply for each comment item that addresses that exact comment's request, context, and outcome.
+
+8. Commit changes
+- If any changes were made, create a commit with a clear message referencing the PR and summarizing the resolution.
+- Prompt the user to review and confirm the commit message before finalizing.
+- When suggesting or performing a push, use the discovered git remote name.
+- Prompt the user to push the commit if they have permissions, or provide instructions if they do not.
+- Prompt the user to reply to each original PR comment with a comment-specific response and link to the relevant commit or code location, if appropriate.
+- Prompt the user to mark review threads as resolved in GitHub if they have permissions, or provide instructions if they do not.
+
+## Output Format
+1. PR Scope
+- Repo
+- PR number
+- Unresolved review threads found
+- Discussion comments found (if enabled)
+
+2. Unresolved Review Feedback (Actionable)
+- Item: <comment url>
+- Location: <file>:<line>
+- Author: <login>
+- Request summary: <concise>
+- Action taken: <change or rationale>
+- Status: Fixed | Needs Clarification | Blocked
+- Evidence: <tests/diagnostics>
+- Suggested reply: <specific response for this exact comment>
+
+3. Discussion Comments (Informational, optional)
+- Item: <comment url>
+- Author: <login>
+- Summary: <concise>
+- Notes: <if converted to actionable task, explain>
+- Suggested reply: <specific response for this exact comment>
+
+4. Validation
+- Commands run
+- Filters used
+- Pass/fail summary
+- Remaining warnings/errors
+
+5. Final Summary
+- Files changed
+- Number fixed
+- Number needing clarification
+- Number blocked
+- Number informational
+- Recommended next step
+
+## Rules
+- Do not invent comments; only act on data fetched from gh.
+- Review-thread resolution tracking is authoritative for unresolved state.
+- Keep behavior-compatible edits unless feedback explicitly requires change.
+- If no unresolved review threads exist, report that explicitly.
+- If auth or permission fails, report exact failure and minimum required user action.
+- Do not use `set -e` in bash commands or scripts.
+- After each terminal step, verify the bash session is still alive; if it died, report it immediately, start a new session, and continue from the last confirmed checkpoint.
+- Use the discovered git remote name consistently anywhere a remote is required.
+- Do not post generic batch replies; each reply must be tailored to the specific comment content and its exact resolution status.

AGENTS.md

@@ -5,6 +5,7 @@ This document provides guidance for AI coding agents working with the Microsoft.
 ## Quick Start
 
 ### Essential Context Files
+
 Before making changes, agents should be aware of:
 
 | File | Purpose |
@@ -15,6 +16,7 @@ Before making changes, agents should be aware of:
 | [.github/copilot-instructions.md](.github/copilot-instructions.md) | Copilot-specific instructions |
 
 ### Detailed Technical Instructions
+
 The `.github/instructions/` directory contains comprehensive guides:
 
 | Guide | Coverage |
@@ -29,6 +31,7 @@ The `.github/instructions/` directory contains comprehensive guides:
 | [features.instructions.md](.github/instructions/features.instructions.md) | Feature reference, keywords |
 | [documentation.instructions.md](.github/instructions/documentation.instructions.md) | Documentation and samples |
 | [external-resources.instructions.md](.github/instructions/external-resources.instructions.md) | Docs links, version matrix, external references |
+| [ado-work-items-markdown.instructions.md](.github/instructions/ado-work-items-markdown.instructions.md) | Ensure Azure DevOps work item descriptions are Markdown and preserve newlines |
 
 ## Workflow Prompts
 
@@ -66,6 +69,7 @@ Do **not** create branches directly under `main`, `dev/`, or any other top-level
 ## Common Tasks
 
 ### Bug Fix Workflow
+
 1. Understand the issue from the bug report
 2. Locate relevant code in `src/Microsoft.Data.SqlClient/src/` (do NOT modify legacy `netcore/src/` or `netfx/src/`)
 3. Write a failing test that reproduces the issue
@@ -74,6 +78,7 @@ Do **not** create branches directly under `main`, `dev/`, or any other top-level
 6. Update documentation if behavior changes
 
 ### Feature Implementation
+
 1. Review the feature specification
 2. Plan the implementation (see `implement-feature` prompt)
 3. Update reference assemblies if adding public APIs
@@ -82,20 +87,23 @@ Do **not** create branches directly under `main`, `dev/`, or any other top-level
 6. Do not edit `CHANGELOG.md` directly; instead, add a suggested release-note entry (per `.github/copilot-instructions.md`) in the PR description or via the release-notes workflow/prompt.
 
 ### Adding Connection String Keywords
+
 1. Add to `SqlConnectionStringBuilder`
 2. Update connection string parser
 3. Default to backward-compatible value
 4. Add tests for new keyword
 5. Document in feature reference
 
 ### Protocol Changes
+
 1. Reference MS-TDS specification
 2. Update `TdsEnums.cs` for new constants
 3. Implement in `TdsParser.cs` and related files
 4. Test against multiple SQL Server versions
 5. Consider backward compatibility
 
 ### Performance Optimization
+
 1. Profile the issue using benchmarks or traces
 2. Identify allocation hotspots (see `perf-optimization` prompt)
 3. Apply patterns: `ArrayPool<T>`, `Span<T>`, static/cached instances, source generation
@@ -105,13 +113,15 @@ Do **not** create branches directly under `main`, `dev/`, or any other top-level
 
 
 ### Key Documentation Links
+
 - [Microsoft.Data.SqlClient on Microsoft Learn](https://learn.microsoft.com/sql/connect/ado-net/introduction-microsoft-data-sqlclient-namespace)
 - [MS-TDS Protocol Specification](https://learn.microsoft.com/openspecs/windows_protocols/ms-tds)
 - [SQL Server Documentation](https://learn.microsoft.com/sql/sql-server/)
 
 ## Repository Policies
 
 See the `policy/` directory for:
+
 - [coding-best-practices.md](policy/coding-best-practices.md) - Programming standards
 - [coding-style.md](policy/coding-style.md) - Code formatting guidelines
 - [review-process.md](policy/review-process.md) - PR review requirements