Agents | Add Azure DevOps work item markdown formatting guide & PR feedback prompt#4253
Agents | Add Azure DevOps work item markdown formatting guide & PR feedback prompt#4253paulmedynski wants to merge 4 commits into
Conversation
paulmedynski
added
the
Area\Engineering
There was a problem hiding this comment.
Pull request overview
Adds a new repository instruction guide documenting a safe, repeatable workflow for updating Azure DevOps work item descriptions to Markdown while preserving newline integrity, and links it from the agent guidance index.
Changes:
- Added a new instruction file under
.github/instructions/coveringaz restJSON-patch patterns and verification scripts forSystem.DescriptionMarkdown formatting. - Updated
AGENTS.mdto reference the new guide in the “Detailed Technical Instructions” table. - Minor formatting tweaks in
AGENTS.md(additional blank lines for readability).
Reviewed changes
Copilot reviewed 2 out of 2 changed files in this pull request and generated 4 comments.
| File | Description |
|---|---|
.github/instructions/ado-work-items-markdown.instructions.md |
New guide documenting Markdown formatting rules, safe update steps, and post-update verification checks for ADO work items. |
AGENTS.md |
Adds a link to the new ADO work item Markdown guide in the technical instructions table (plus minor spacing adjustments). |
paulmedynski
changed the title
Pull request was converted to draft
- Create ado-work-items-markdown.instructions.md with safe patterns for markdown description updates - Document two-step conversion for changing field format without data loss - Include newline integrity checks and batch verification scripts - Update AGENTS.md to link new instruction guide for discoverability
- Tested it with this PRs comments.
paulmedynski
force-pushed
the
dev/paul/ado-instructions
branch
from
5fc9bec to
b67e3bb
Compare
paulmedynski
left a comment
paulmedynski
left a comment
There was a problem hiding this comment.
Submitting pending review
| ## Quick Start | ||
|
|
||
| ### Essential Context Files | ||
|
|
There was a problem hiding this comment.
Fixed linter errors in this file. I have another PR somewhere to introduce proper MarkDown linting configuration and checking.
paulmedynski
changed the title
Use file-based capture (pipe to file) instead of command substitution to preserve trailing newlines. Step 3 now uses jq --rawfile to read back the description byte-for-byte.
paulmedynski
force-pushed
the
dev/paul/ado-instructions
branch
from
b67e3bb to
97a05e7
Compare
| - 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. |
There was a problem hiding this comment.
Most of this should be available via the github mcp server. Did you try using that? Are there some things only available via cli?
The mcp tools are nice because we can have a standard setup for everyone and we can limit tool access in the prompt frontmatter.
There was a problem hiding this comment.
Do you mean this? https://github.com/github/github-mcp-server
I will install it and try it for a while, but I'd like these instructions available to use while I vet the MCP approach.
There was a problem hiding this comment.
It can't perform the first task I tried:
I asked it what its capabilities are:
Here's what I can do in this conversation:
Available capabilities:
- Semantic code search — I can search the dotnet/SqlClient codebase using natural language queries to find relevant code.
- Conversation & analysis — I can explain code, draft PR descriptions, suggest fixes, help with architecture decisions, write code snippets, and answer questions about the repository.
What I cannot do here:
- Read or update PR descriptions, titles, or labels
- Fetch PR diffs or file changes
- Create/close issues or PRs
- Push commits or create branches
- Run builds or tests
- Access GitHub API endpoints directly
Can you configure me to have more capabilities?
Yes — depending on your environment:
- GitHub Copilot in VS Code / IDE — I may have access to file reading, terminal execution, and more tools.
- GitHub Copilot Extensions — Custom extensions can grant me additional GitHub API access.
- GitHub Actions with Copilot — In CI workflows, I can be given tools to interact with PRs, issues, etc.
- GitHub Copilot Chat on github.com — On the github.com interface, I sometimes have richer context about the PR you're viewing.
For your original request (updating PR #4329's description), you could:
- Paste the current description and the list of changes here, and I'll draft an updated one for you to copy back.
- Or use the gh CLI: gh pr view 4329 --json body,files and share the output with me.
Hehe - it suggested I use the gh CLI 😉
There was a problem hiding this comment.
You may not have the tools enabled? I've been using it to do PR management.
I won't block the PR, but I do think we should try to avoid requiring direct terminal access unless it's really required for the skill/prompt.
Description
This PR adds comprehensive instructions for ensuring markdown content is properly formatted when creating or updating Azure DevOps work items, and a reusable prompt for reviewing PR feedback.
Changes
New file:
.github/instructions/ado-work-items-markdown.instructions.mdNew file:
.github/prompts/review-pr-feedback.prompt.mdghCLIUpdated:
AGENTS.mdContext
These instructions document the workflow discovered while updating 26 work items (4 stories + 22 tasks) for the pipeline implementation project. The patterns ensure:
The PR feedback prompt was developed and used to help work through this PRs feedback.