microsoft/hve-core
Publicmirrored fromhttps://github.com/microsoft/hve-coreAvailable
.github/instructions/ado-create-pull-request.instructions.md
973lines · modecode
| 1 | --- |
| 2 | description: "Required protocol for creating Azure DevOps pull requests with work item discovery, reviewer identification, and automated linking." |
| 3 | applyTo: '**/.copilot-tracking/pr/new/**' |
| 4 | --- |
| 5 | |
| 6 | # Azure DevOps Pull Request Creation & Workflow |
| 7 | |
| 8 | Follow all instructions from #file:./ado-wit-planning.instructions.md for planning file conventions while executing this workflow. |
| 9 | |
| 10 | ## Scope |
| 11 | |
| 12 | Apply this procedure when creating a new Azure DevOps pull request with: |
| 13 | |
| 14 | * Automated PR description generation from branch changes |
| 15 | * Discovery and linking of related User Stories and Bugs |
| 16 | * Identification of potential reviewers from git history |
| 17 | * Complete traceability through planning documents |
| 18 | * Automated PR creation via Azure DevOps MCP tools |
| 19 | |
| 20 | * Output planning files under `.copilot-tracking/pr/new/<normalized-branch-name>/` |
| 21 | * Default Azure DevOps project: `${input:adoProject}` |
| 22 | * Default repository: `${input:repository}` |
| 23 | |
| 24 | ## Deliverables |
| 25 | |
| 26 | * `pr-reference.xml` - Complete git diff and commit history |
| 27 | * `pr.md` - Generated pull request description |
| 28 | * `pr-analysis.md` - Analysis of changes and discovered work items |
| 29 | * `reviewer-analysis.md` - Potential reviewers with rationale |
| 30 | * `planning-log.md` - Structured operational log |
| 31 | * `handoff.md` - Final PR creation plan with all details |
| 32 | * Conversational recap summarizing PR creation results with URL |
| 33 | |
| 34 | ## Tooling |
| 35 | |
| 36 | * `run_in_terminal` (zsh) for git operations: |
| 37 | 1. Sync remote base branch: `git fetch <remote> <branch-name> --prune` |
| 38 | 2. Generate PR reference XML: `scripts/dev-tools/pr-ref-gen.sh --base-branch "${input:baseBranch}" --output ".copilot-tracking/pr/new/<normalized-branch-name>/pr-reference.xml"` |
| 39 | 3. Get current user: `git config user.email` |
| 40 | 4. Get file contributors: `git log --all --pretty=format:'%H %an <%ae>' -- <file-pattern> | head -20` |
| 41 | * Azure DevOps MCP tools: |
| 42 | * `mcp_ado_search_workitem` for work item discovery |
| 43 | * `mcp_ado_wit_get_work_item` or `mcp_ado_wit_get_work_items_batch_by_ids` for hydration |
| 44 | * `mcp_ado_repo_create_pull_request` for PR creation |
| 45 | * `mcp_ado_wit_link_work_item_to_pull_request` for linking work items |
| 46 | * `mcp_ado_core_get_identity_ids` for resolving reviewer emails to Azure DevOps identity IDs |
| 47 | * `mcp_ado_repo_update_pull_request_reviewers` for adding/removing reviewers programmatically |
| 48 | * Workspace utilities: `list_dir`, `read_file`, `grep_search` |
| 49 | * Persist all tool output into planning files per #file:./ado-wit-planning.instructions.md |
| 50 | |
| 51 | <!-- <tracking-directory-structure> --> |
| 52 | ## Tracking Directory Structure |
| 53 | |
| 54 | All PR creation tracking artifacts MUST reside in `.copilot-tracking/pr/new/{{normalized branch name}}`. |
| 55 | |
| 56 | ```plaintext |
| 57 | .copilot-tracking/ |
| 58 | pr/ |
| 59 | new/ |
| 60 | {{normalized branch name}}/ |
| 61 | pr-reference.xml # Generated git diff and commit history |
| 62 | pr.md # Generated PR description |
| 63 | pr-analysis.md # Change analysis and work item findings |
| 64 | reviewer-analysis.md # Potential reviewer analysis |
| 65 | planning-log.md # Operational log |
| 66 | handoff.md # Final PR creation plan |
| 67 | ``` |
| 68 | |
| 69 | **Branch Name Normalization Rules**: |
| 70 | |
| 71 | * Convert to lowercase characters |
| 72 | * Replace `/` with `-` |
| 73 | * Strip special characters except hyphens |
| 74 | * Example: `feat/ACR-Private-Public` → `feat-acr-private-public` |
| 75 | <!-- </tracking-directory-structure> --> |
| 76 | |
| 77 | <!-- <planning-file-formats> --> |
| 78 | ## Planning File Formats |
| 79 | |
| 80 | ### pr-analysis.md |
| 81 | |
| 82 | <!-- <template-pr-analysis-md> --> |
| 83 | ````markdown |
| 84 | # Pull Request Analysis - [Branch Name] |
| 85 | * **Source Branch**: [Source branch name] |
| 86 | * **Target Branch**: [Target branch name] |
| 87 | * **Project**: [Azure DevOps project] |
| 88 | * **Repository**: [Repository name or ID] |
| 89 | |
| 90 | ## Change Summary |
| 91 | |
| 92 | [1-5 sentence summary of what changed based on pr-reference.xml analysis] |
| 93 | |
| 94 | ## Changed Files |
| 95 | |
| 96 | * [file/path/one.ext]: [Brief description of changes] |
| 97 | * [file/path/two.ext]: [Brief description of changes] |
| 98 | |
| 99 | ## Commit Summary |
| 100 | * [Aggregated summary of commit messages] |
| 101 | |
| 102 | ## Work Item Discovery |
| 103 | |
| 104 | ### Keyword Groups for Search |
| 105 | |
| 106 | 1. [Keyword group 1]: [term1 OR term2 OR "multi word term"] |
| 107 | 2. [Keyword group 2]: [term1 OR term2] |
| 108 | |
| 109 | ### Discovered Work Items |
| 110 | |
| 111 | #### ADO-[Work Item ID] - [Similarity Score] - [Type] |
| 112 | * **Title**: [Work item title] |
| 113 | * **State**: [Current state] |
| 114 | * **Relevance Reasoning**: [Why this work item relates to the PR] |
| 115 | * **User Decision**: [Pending|Link|Skip] |
| 116 | |
| 117 | ## Notes |
| 118 | |
| 119 | * [Optional notes about the analysis] |
| 120 | ```` |
| 121 | <!-- </template-pr-analysis-md> --> |
| 122 | |
| 123 | ### reviewer-analysis.md |
| 124 | |
| 125 | <!-- <template-reviewer-analysis-md> --> |
| 126 | ````markdown |
| 127 | # Reviewer Analysis - [Branch Name] |
| 128 | * **Current User**: [Current git user email] |
| 129 | * **Changed Files**: [Count] |
| 130 | |
| 131 | ## Contributor Analysis |
| 132 | |
| 133 | ### Changed File: [file/path/one.ext] |
| 134 | * **Recent Contributors** (last 20 commits): |
| 135 | * [Contributor 1 Name] <[email]> - [commit count] commits |
| 136 | * [Contributor 2 Name] <[email]> - [commit count] commits |
| 137 | |
| 138 | ### Changed File: [file/path/two.ext] |
| 139 | * **Recent Contributors** (last 20 commits): |
| 140 | * [Contributor 1 Name] <[email]> - [commit count] commits |
| 141 | |
| 142 | ### Surrounding Files: [directory/**] |
| 143 | * **Recent Contributors** (last 20 commits): |
| 144 | * [Contributor Name] <[email]> - [commit count] commits |
| 145 | |
| 146 | ## Potential Reviewers (excluding current user) |
| 147 | |
| 148 | 1. **[Reviewer 1 Name]** <[email]> |
| 149 | * **Contribution Score**: [High|Medium|Low] |
| 150 | * **Files**: [List of changed files they contributed to] |
| 151 | * **Rationale**: [Why they would be a good reviewer] |
| 152 | * **User Decision**: [Pending|Required|Optional|Skip] |
| 153 | |
| 154 | 2. **[Reviewer 2 Name]** <[email]> |
| 155 | * **Contribution Score**: [High|Medium|Low] |
| 156 | * **Files**: [List of changed files they contributed to] |
| 157 | * **Rationale**: [Why they would be a good reviewer] |
| 158 | * **User Decision**: [Pending|Required|Optional|Skip] |
| 159 | |
| 160 | ## Reviewer Recommendation |
| 161 | |
| 162 | * **Recommended Reviewers**: [List of high-contribution reviewers] |
| 163 | * **Additional Reviewers**: [List of lower-contribution reviewers] |
| 164 | ```` |
| 165 | <!-- </template-reviewer-analysis-md> --> |
| 166 | |
| 167 | ### handoff.md |
| 168 | |
| 169 | <!-- <template-handoff-md> --> |
| 170 | ````markdown |
| 171 | # Pull Request Creation Handoff |
| 172 | * **Project**: [Azure DevOps project] |
| 173 | * **Repository**: [Repository name or ID] |
| 174 | * **Repository ID**: [Repository ID for MCP tool] |
| 175 | * **Source Branch**: [Source branch name] |
| 176 | * **Target Branch**: [Target branch name] |
| 177 | * **Is Draft**: [true|false] |
| 178 | |
| 179 | ## Planning Files |
| 180 | |
| 181 | * .copilot-tracking/pr/new/[normalized-branch-name]/handoff.md |
| 182 | * .copilot-tracking/pr/new/[normalized-branch-name]/pr-analysis.md |
| 183 | * .copilot-tracking/pr/new/[normalized-branch-name]/reviewer-analysis.md |
| 184 | * .copilot-tracking/pr/new/[normalized-branch-name]/planning-log.md |
| 185 | * .copilot-tracking/pr/new/[normalized-branch-name]/pr.md |
| 186 | |
| 187 | ## PR Details |
| 188 | |
| 189 | ### Title |
| 190 | |
| 191 | [Generated PR title from pr.md] |
| 192 | |
| 193 | ### Description |
| 194 | |
| 195 | ```markdown |
| 196 | [Complete PR description from pr.md] |
| 197 | ``` |
| 198 | |
| 199 | ## Work Items to Link |
| 200 | |
| 201 | * [ ] ADO-[Work Item ID] - [Type] - [Title] |
| 202 | * **Similarity**: [Score] |
| 203 | * **Reason**: [Why linking this work item] |
| 204 | * [ ] ADO-[Work Item ID] - [Type] - [Title] |
| 205 | * **Similarity**: [Score] |
| 206 | * **Reason**: [Why linking this work item] |
| 207 | |
| 208 | **Total Work Items**: [Count] |
| 209 | |
| 210 | ## Reviewers to Add |
| 211 | |
| 212 | ### Reviewers |
| 213 | |
| 214 | * [ ] [Reviewer Name] <[email]> |
| 215 | * **Rationale**: [Why they should review] |
| 216 | |
| 217 | * [ ] [Reviewer Name] <[email]> |
| 218 | * **Rationale**: [Why they should review] |
| 219 | |
| 220 | **Total Reviewers**: [Count] |
| 221 | |
| 222 | ## MCP Tool Call Plan |
| 223 | |
| 224 | ### 2. Create Pull Request |
| 225 | |
| 226 | **Tool**: `mcp_ado_repo_create_pull_request` |
| 227 | |
| 228 | **Parameters**: |
| 229 | * `repositoryId`: "[Repository ID]" |
| 230 | * `sourceRefName`: "refs/heads/[source-branch-name]" |
| 231 | * `targetRefName`: "refs/heads/[target-branch-name]" |
| 232 | * `title`: "[PR title from pr.md first line WITHOUT the markdown heading marker hash]" |
| 233 | * Example: `feat(scope): description` (NOT `# feat(scope): description`) |
| 234 | * `description`: "[PR description from pr.md body WITH full markdown formatting]" |
| 235 | * `isDraft`: [true|false] |
| 236 | |
| 237 | **Expected Result**: Pull request created with ID [PR-ID] |
| 238 | |
| 239 | ### 2. Link Work Items |
| 240 | |
| 241 | **Tool**: `mcp_ado_wit_link_work_item_to_pull_request` (call once per work item) |
| 242 | |
| 243 | **Parameters for each work item**: |
| 244 | * `projectId`: "[Project ID]" |
| 245 | * `repositoryId`: "[Repository ID]" |
| 246 | * `pullRequestId`: [PR-ID from step 1] |
| 247 | * `workItemId`: [Work Item ID] |
| 248 | |
| 249 | **Total Calls**: [Count of work items to link] |
| 250 | |
| 251 | ### 3. Add Reviewers |
| 252 | |
| 253 | **Tool**: `mcp_ado_repo_update_pull_request_reviewers` |
| 254 | |
| 255 | **Parameters**: |
| 256 | * `repositoryId`: "[Repository ID]" |
| 257 | * `pullRequestId`: [PR-ID from step 1] |
| 258 | * `reviewerIds`: [[Array of resolved identity GUIDs from mcp_ado_core_get_identity_ids]] |
| 259 | * `action`: "add" |
| 260 | |
| 261 | **Expected Result**: Reviewers added to pull request [PR-ID] |
| 262 | |
| 263 | **Note**: Reviewers without resolved identity IDs must be added manually via Azure DevOps UI. |
| 264 | |
| 265 | ## User Signoff |
| 266 | |
| 267 | * [ ] PR details reviewed and approved |
| 268 | * [ ] Work items confirmed |
| 269 | * [ ] Reviewers confirmed |
| 270 | * [ ] Ready to create PR |
| 271 | |
| 272 | **User Confirmation**: [Pending|Approved] |
| 273 | ```` |
| 274 | <!-- </template-handoff-md> --> |
| 275 | <!-- </planning-file-formats> --> |
| 276 | |
| 277 | ## Workflow Overview |
| 278 | |
| 279 | This workflow follows a progressive confirmation model where user reviews and approves each section before proceeding: |
| 280 | |
| 281 | 1. **Setup & Analysis** (Phases 1-4): Silent preparation - generate artifacts, analyze changes, discover work items and reviewers |
| 282 | 2. **User Review & Confirmation** (Phase 5): Present information in stages with confirmation gates |
| 283 | 3. **PR Creation** (Phase 6): Execute after final user signoff |
| 284 | 4. **Completion** (Phase 7): Deliver recap with PR URL |
| 285 | |
| 286 | **Critical**: Do NOT present all information at once. Present each confirmation gate separately and wait for user response before proceeding to the next gate. |
| 287 | |
| 288 | ### No-Gates Mode |
| 289 | |
| 290 | When `${input:noGates}` is true: |
| 291 | |
| 292 | * Skip Phase 5 (all confirmation gates) entirely |
| 293 | * After completing Phase 4, proceed directly to Phase 6 |
| 294 | * Use all discovered work items (no user selection) |
| 295 | * If Phase 3a created a work item, use that created work item automatically |
| 296 | * Add minimum of 2 optional reviewers (top 2 by contribution score) |
| 297 | * Create PR immediately with all discovered linkages |
| 298 | * Deliver final recap in Phase 7 as usual |
| 299 | |
| 300 | ## Workflow |
| 301 | |
| 302 | ### Phase 1 – Setup & PR Reference Generation (Silent) |
| 303 | |
| 304 | Execute without presenting details to user: |
| 305 | |
| 306 | 1. Determine normalized branch name from `${input:sourceBranch}` or current git branch. |
| 307 | 2. Create planning directory: `.copilot-tracking/pr/new/<normalized-branch-name>/` |
| 308 | 3. Initialize `planning-log.md` with Phase-1 status. |
| 309 | 4. Check if `pr-reference.xml` exists: |
| 310 | * If exists: Use existing file silently. |
| 311 | * If not exists: Generate using `scripts/dev-tools/pr-ref-gen.sh` with optional `--no-md-diff` flag if `${input:includeMarkdown}` is false. |
| 312 | 5. Read complete `pr-reference.xml` (page through if >2000 lines). |
| 313 | 6. Log artifact in `planning-log.md` with status `Complete`. |
| 314 | |
| 315 | ### Phase 2 – Generate PR Description (Silent) |
| 316 | |
| 317 | Execute without presenting to user yet: |
| 318 | |
| 319 | 1. **CRITICAL**: Analyze `pr-reference.xml` completely before writing any content. |
| 320 | 2. **CRITICAL**: Do NOT invent or assume changes not present in `pr-reference.xml`. |
| 321 | 3. **CRITICAL**: Only include changes visible in `pr-reference.xml`. |
| 322 | 4. Generate `pr.md` in the planning directory (NOT in root) following the PR File Format below. |
| 323 | 5. Extract commit types, scopes, and key changes for PR title and description. |
| 324 | 6. Use past tense for all descriptions. |
| 325 | 7. Describe WHAT changed, not speculating WHY. |
| 326 | 8. Use natural, conversational language that reads like human communication. |
| 327 | 9. Match tone and terminology from commit messages. |
| 328 | 10. Group and order changes by SIGNIFICANCE and IMPORTANCE (most significant first). |
| 329 | 11. Combine related changes into single descriptive points. |
| 330 | 12. Only add sub-bullets when they provide genuine clarification value. |
| 331 | 13. Only include "Notes," "Important," or "Follow-up" sections if supported by commit messages or code comments. |
| 332 | 14. Extract changed file list with descriptions for Gate 1 presentation. |
| 333 | 15. Log generation in `planning-log.md`. |
| 334 | |
| 335 | <!-- <pr-file-format> --> |
| 336 | **PR File Format for pr.md**: |
| 337 | |
| 338 | ```markdown |
| 339 | # {{type}}({{scope}}): {{concise description}} |
| 340 | |
| 341 | {{Summary paragraph of overall changes in natural, human-friendly language}} |
| 342 | |
| 343 | - **{{type}}**(_{{scope}}_): {{description of change with key context included}} |
| 344 | |
| 345 | - **{{type}}**(_{{scope}}_): {{description of change}} |
| 346 | - {{sub-bullet only if it adds genuine clarification value}} |
| 347 | |
| 348 | - **{{type}}**: {{description of change without scope, including essential details}} |
| 349 | |
| 350 | ## Notes (optional) |
| 351 | |
| 352 | - Note 1 identified from code comments or commit message |
| 353 | - Note 2 identified from code comments or commit message |
| 354 | |
| 355 | ## Important (optional) |
| 356 | |
| 357 | - Critical information 1 identified from code comments or commit message |
| 358 | - Warning 2 identified from code comments or commit message |
| 359 | |
| 360 | ## Follow-up Tasks (optional) |
| 361 | |
| 362 | - Task 1 with file reference |
| 363 | - Task 2 with specific component mention |
| 364 | |
| 365 | {{emoji representing the changes}} - Generated by Copilot |
| 366 | ``` |
| 367 | |
| 368 | **Type and Scope**: |
| 369 | |
| 370 | * Determine from commits in `pr-reference.xml` |
| 371 | * Use branch name as primary source for type/scope |
| 372 | * Common types: feat, fix, docs, chore, refactor, test, ci |
| 373 | * Scope should reference component or area affected |
| 374 | |
| 375 | **Title Construction Rules**: |
| 376 | |
| 377 | * Format: `{type}({scope}): {concise description}` |
| 378 | * If branch name is not descriptive, rely on commit messages |
| 379 | * Keep concise but descriptive |
| 380 | |
| 381 | **Never Include**: |
| 382 | |
| 383 | * Changes related to linting errors or auto-generated documentation |
| 384 | * Speculative benefits ("improves security") unless explicit in commits |
| 385 | * Follow-up tasks for documentation or tests (unless in commit messages) |
| 386 | <!-- </pr-file-format> --> |
| 387 | |
| 388 | ### Phase 3 – Discover Related Work Items (Silent) |
| 389 | |
| 390 | **Skip this phase entirely if `${input:workItemIds}` is provided by the user.** |
| 391 | |
| 392 | Execute without presenting to user yet: |
| 393 | |
| 394 | 1. Build ACTIVE KEYWORD GROUPS from: |
| 395 | * Changed file paths (component names, directories) |
| 396 | * Commit messages (subjects and bodies) |
| 397 | * Conventional commit scopes |
| 398 | * Technical terms from diff content |
| 399 | 2. For each keyword group, call `mcp_ado_search_workitem` with: |
| 400 | * `project`: `${input:adoProject}` |
| 401 | * `searchText`: constructed from keyword groups using OR/AND syntax |
| 402 | * `workItemType`: ["User Story", "Bug"] (NEVER include Feature or Epic) |
| 403 | * `state`: Parse `${input:workItemStates}` into array format |
| 404 | * `top`: 50; increment `skip` as needed |
| 405 | * Optional filters: `${input:areaPath}`, `${input:iterationPath}` |
| 406 | 3. Hydrate results via `mcp_ado_wit_get_work_item` (batch variant preferred). |
| 407 | 4. Compute similarity using semantic analysis of: |
| 408 | * Work item title + description vs. PR title + description |
| 409 | * Work item acceptance criteria vs. PR change summary |
| 410 | * Boost for matching commit scopes, file paths, technical terms |
| 411 | 5. Filter work items with similarity >= `${input:similarityThreshold}`. |
| 412 | 6. Capture findings in `pr-analysis.md` with relevance reasoning. |
| 413 | 7. Log discovered work items in `planning-log.md`. |
| 414 | 8. If NO viable work items are discovered (zero work items with similarity >= threshold): |
| 415 | * Proceed to Phase 3a - Create Work Item for PR |
| 416 | * After Phase 3a completion, continue to Phase 4 |
| 417 | |
| 418 | ### Phase 3a – Create Work Item for PR (Conditional) |
| 419 | |
| 420 | **Execute this phase ONLY when Phase 3 discovers zero viable work items.** |
| 421 | |
| 422 | Read in and follow instructions from ado-wit-discovery.instructions.md and ado-update-wit-items.instructions.md to create a work item for this PR: |
| 423 | |
| 424 | 1. **Setup Work Item Discovery Planning**: |
| 425 | * Determine folder name from PR context (e.g., branch name without `feat/`, `fix/`, etc.) |
| 426 | * Create planning directory: `.copilot-tracking/workitems/discovery/<folder-name>/` |
| 427 | * Initialize planning files following ado-wit-discovery.instructions.md templates |
| 428 | |
| 429 | 2. **Reuse PR Analysis Artifacts**: |
| 430 | * Copy or reference `pr-reference.xml` from PR planning directory |
| 431 | * Use existing PR title, description, and change analysis from Phase 2 |
| 432 | * Use existing ACTIVE KEYWORD GROUPS from Phase 3 |
| 433 | * Skip git-branch-diff.xml generation (already have pr-reference.xml) |
| 434 | |
| 435 | 3. **Execute Work Item Discovery Workflow**: |
| 436 | * Follow Phase 1 of ado-wit-discovery.instructions.md using PR artifacts |
| 437 | * Create `artifact-analysis.md` from PR context (commits, files, changes) |
| 438 | * Follow Phase 2 to discover Features for potential parent linking (User Stories only) |
| 439 | * Follow Phase 3 to plan work item creation: |
| 440 | * Create ONE User Story or Bug based on PR content |
| 441 | * Derive work item type from branch name or commit type (feat → User Story, fix → Bug) |
| 442 | * Title: Extract from PR title following work item conventions |
| 443 | * Description: Adapt from PR description with rationale |
| 444 | * Acceptance Criteria: Derive from PR changes and commit messages |
| 445 | * Link to parent Feature if discovered (User Stories only) |
| 446 | * Follow Phase 4 to assemble `handoff.md` with Create action |
| 447 | |
| 448 | 4. **Execute Work Item Creation**: |
| 449 | * Follow instructions from ado-update-wit-items.instructions.md |
| 450 | * Create `handoff-logs.md` in work item planning directory |
| 451 | * Process the Create action from `handoff.md` |
| 452 | * Use `mcp_ado_wit_create_work_item` to create the work item |
| 453 | * Capture created work item ID in `handoff-logs.md` |
| 454 | * Log creation result in PR `planning-log.md` |
| 455 | |
| 456 | 5. **Link Created Work Item to PR Flow**: |
| 457 | * Store created work item ID for use in Phase 6 linking |
| 458 | * Update PR `pr-analysis.md` with created work item details |
| 459 | * Log in PR `planning-log.md` that work item was created for this PR |
| 460 | |
| 461 | **Note**: This phase creates exactly ONE work item representing the PR's purpose. Skip Feature/Epic creation. Keep planning files in work item discovery folder separate from PR planning folder. |
| 462 | |
| 463 | ### Phase 4 – Identify Potential Reviewers (Silent) |
| 464 | |
| 465 | Execute without presenting to user yet: |
| 466 | |
| 467 | 1. Get current user email: `git config user.email` |
| 468 | 2. For each changed file in `pr-reference.xml`: |
| 469 | * Extract file path |
| 470 | * Get recent contributors: `git log --all --pretty=format:'%H %an <%ae>' -- <file-path> | head -20` |
| 471 | * Parse output to count commits per author |
| 472 | 3. For surrounding directories of changed files: |
| 473 | * Use parent directory patterns (e.g., `path/to/dir/**`) |
| 474 | * Get recent contributors: `git log --all --pretty=format:'%H %an <%ae>' -- <dir-pattern> | head -20` |
| 475 | 4. Aggregate contributors across all changed files and directories: |
| 476 | * Count total commits per contributor |
| 477 | * Exclude current user |
| 478 | * Rank by contribution score (High: >10 commits, Medium: 3-10, Low: 1-2) |
| 479 | 5. Resolve Azure DevOps identity IDs: |
| 480 | * For each unique reviewer email, call `mcp_ado_core_get_identity_ids` with `searchFilter` set to the email |
| 481 | * Extract `id` (GUID) from response and store with reviewer record |
| 482 | * If no match or multiple matches found, mark for manual addition |
| 483 | 6. Capture analysis in `reviewer-analysis.md` with rationale and resolved identity IDs. |
| 484 | 7. Log potential reviewers and resolution status in `planning-log.md`. |
| 485 | |
| 486 | ### Phase 5 – User Review & Confirmation (Progressive Gates) |
| 487 | |
| 488 | **Skip this entire phase if `${input:noGates}` is true. Proceed directly to Phase 6 with:** |
| 489 | |
| 490 | * All discovered work items from Phase 3 |
| 491 | * If Phase 3a created a work item, use that created work item |
| 492 | * Top 2 reviewers by contribution score from Phase 4 (minimum 2 optional reviewers) |
| 493 | * Auto-approve all content from Phases 1-4 |
| 494 | |
| 495 | **Critical**: Present each gate separately. Wait for user approval/modification before proceeding to next gate. |
| 496 | |
| 497 | #### Gate 1: Changed Files Review |
| 498 | |
| 499 | 1. Extract all changed files from `pr-reference.xml`. |
| 500 | 2. For each file, provide brief description of changes from diff analysis. |
| 501 | 3. Perform quality review and identify: |
| 502 | * Accidental or unintended changes (e.g., debug code, commented code) |
| 503 | * Missing files that should be tracked |
| 504 | * Extra files that should not be included (e.g., build artifacts, temp files) |
| 505 | * Security issues (secrets, credentials, PII) |
| 506 | * Compliance issues (non-compliant language, FIXME, WIP, etc in committed code) |
| 507 | * Code quality concerns (styling violations, linting issues) |
| 508 | |
| 509 | **File Count Handling**: |
| 510 | |
| 511 | * If ≤ 50 files: Present full list inline with change descriptions |
| 512 | * If > 50 files: Provide summary statistics and link to `pr-analysis.md`, instruct user to review and confirm when ready |
| 513 | |
| 514 | <!-- <example-gate1-small-changeset> --> |
| 515 | **Presentation Format (≤50 files)**: |
| 516 | |
| 517 | ```markdown |
| 518 | ## 📄 Changed Files Review |
| 519 | |
| 520 | I've analyzed [count] changed files in your PR: |
| 521 | |
| 522 | ### Modified Files |
| 523 | |
| 524 | 1. **[path/to/file1.ext]** |
| 525 | * [Brief description of changes] |
| 526 | |
| 527 | 2. **[path/to/file2.ext]** |
| 528 | * [Brief description of changes] |
| 529 | |
| 530 | ### Quality Review |
| 531 | |
| 532 | ✅ **No Issues Found** |
| 533 | |
| 534 | [OR if issues found:] |
| 535 | |
| 536 | ⚠️ **Issues Requiring Attention**: |
| 537 | * [Issue 1 with file reference] |
| 538 | * [Issue 2 with file reference] |
| 539 | |
| 540 | Please review the changes. You can: |
| 541 | * Continue ("Approved" or "Continue") |
| 542 | * Remove files ("Remove [filename]") |
| 543 | * Add missing files ("Add [filename]") |
| 544 | * Make other modifications (specify what to change) |
| 545 | ``` |
| 546 | <!-- </example-gate1-small-changeset> --> |
| 547 | |
| 548 | <!-- <example-gate1-large-changeset> --> |
| 549 | **Presentation Format (>50 files)**: |
| 550 | |
| 551 | ```markdown |
| 552 | ## 📄 Changed Files Review |
| 553 | |
| 554 | Your PR includes **[count] changed files** - this is a large changeset. |
| 555 | |
| 556 | **Summary**: |
| 557 | * Modified: [count] |
| 558 | * Added: [count] |
| 559 | * Deleted: [count] |
| 560 | |
| 561 | **Key Changes**: |
| 562 | * [Top 3-5 most significant changes with file paths] |
| 563 | |
| 564 | **Quality Review**: |
| 565 | [✅ No major issues found OR ⚠️ List of issues requiring attention] |
| 566 | |
| 567 | 📋 **Complete file list**: `.copilot-tracking/pr/new/[normalized-branch]/pr-analysis.md` |
| 568 | |
| 569 | Please review the full analysis and let me know when to continue or if you need modifications. |
| 570 | ``` |
| 571 | <!-- </example-gate1-large-changeset> --> |
| 572 | |
| 573 | **Wait for user response before proceeding to Gate 2.** |
| 574 | |
| 575 | #### Gate 2: PR Title & Description Review |
| 576 | |
| 577 | 1. Extract PR title from `pr.md` first line: |
| 578 | * Remove leading `#` and whitespace |
| 579 | * Example: `# feat(scope): description` → `feat(scope): description` |
| 580 | * This cleaned title will be used for Azure DevOps PR creation |
| 581 | 2. Present complete PR description from `pr.md` body (after first line): |
| 582 | * Preserve all markdown formatting including headings with `#` markers |
| 583 | 3. Perform security/compliance analysis on `pr-reference.xml`: |
| 584 | * Customer information leaks (PII, customer data) |
| 585 | * Secrets or credentials (API keys, passwords, tokens) |
| 586 | * Non-compliant language (FIXME, WIP, etc in committed code) |
| 587 | * Unintended changes or accidental file inclusion |
| 588 | * Missing referenced files |
| 589 | |
| 590 | <!-- <example-gate2> --> |
| 591 | **Presentation Format**: |
| 592 | |
| 593 | ```markdown |
| 594 | ## 📝 Pull Request Title & Description |
| 595 | |
| 596 | **Title**: |
| 597 | ```text |
| 598 | |
| 599 | [Generated title from pr.md] |
| 600 | |
| 601 | ``` |
| 602 | |
| 603 | **Description**: |
| 604 | |
| 605 | ```markdown |
| 606 | [Complete PR description from pr.md] |
| 607 | ``` |
| 608 | |
| 609 | **Security & Compliance Check**: |
| 610 | [Details of security and compliance check] |
| 611 | |
| 612 | Please review the PR content. You can: |
| 613 | |
| 614 | * Continue ("Approved" or "Continue") |
| 615 | * Modify title ("Change title to: [new title]") |
| 616 | * Modify description ("Update description: [changes]") |
| 617 | * Request regeneration ("Regenerate description") |
| 618 | |
| 619 | ```text |
| 620 | <!-- </example-gate2> --> |
| 621 | |
| 622 | **Wait for user response before proceeding to Gate 3.** |
| 623 | |
| 624 | #### Gate 3: Work Items Review |
| 625 | |
| 626 | 1. If `${input:workItemIds}` was provided: Present those work items for confirmation. |
| 627 | 2. If work item was created in Phase 3a: Present the created work item for confirmation. |
| 628 | 3. If discovered in Phase 3: Present up to 10 highest similarity work items. |
| 629 | 4. For each work item provide: |
| 630 | * Work item ID and type |
| 631 | * Title |
| 632 | * Current state |
| 633 | * Similarity score (percentage) - or "Created for this PR" if from Phase 3a |
| 634 | * 1-2 sentence relevance reasoning |
| 635 | |
| 636 | <!-- <example-gate3> --> |
| 637 | **Presentation Format**: |
| 638 | |
| 639 | ```markdown |
| 640 | ## 🔗 Work Items to Link |
| 641 | |
| 642 | [If work item was created in Phase 3a:] |
| 643 | I created a new work item for this PR since no existing work items matched: |
| 644 | |
| 645 | ### ADO-[ID] - [Type] - New |
| 646 | **Title**: [Work item title] |
| 647 | **Status**: Created for this PR |
| 648 | **Why link**: Work item created to track this pull request's changes |
| 649 | |
| 650 | [If work items were discovered in Phase 3:] |
| 651 | I found [count] work items that may relate to your changes: |
| 652 | |
| 653 | ### ADO-[ID] - [Type] - [State] |
| 654 | **Title**: [Work item title] |
| 655 | **Similarity**: [XX]% |
| 656 | **Why link**: [1-2 sentence relevance explanation] |
| 657 | |
| 658 | [Repeat for each work item, maximum 10] |
| 659 | |
| 660 | Which work items should be linked to this PR? |
| 661 | * Link specific IDs: "Link [ID1], [ID2]" |
| 662 | * Link all: "Link all" |
| 663 | * Skip linking: "None" or "Skip" |
| 664 | * See more options: "Show more" |
| 665 | ``` |
| 666 | <!-- </example-gate3> --> |
| 667 | |
| 668 | **Wait for user response and capture selections. Proceed to Gate 4.** |
| 669 | |
| 670 | #### Gate 4: Reviewers Review |
| 671 | |
| 672 | 1. Present suggested reviewers from `reviewer-analysis.md`. |
| 673 | 2. Separate into Recommended and Additional categories based on contribution score. |
| 674 | 3. Provide contribution score and rationale for each. |
| 675 | |
| 676 | <!-- <example-gate4> --> |
| 677 | **Presentation Format**: |
| 678 | |
| 679 | ```markdown |
| 680 | ## 👥 Suggested Reviewers |
| 681 | |
| 682 | Based on git history of changed files: |
| 683 | |
| 684 | ### Recommended Reviewers |
| 685 | |
| 686 | 1. **[Name]** ([email]) |
| 687 | * Contribution: [High/Medium] - [XX] commits to changed files |
| 688 | * Rationale: [Why they should review] |
| 689 | |
| 690 | ### Additional Reviewers |
| 691 | |
| 692 | 1. **[Name]** ([email]) |
| 693 | * Contribution: [Medium/Low] - [XX] commits |
| 694 | * Rationale: [Why they might be helpful] |
| 695 | |
| 696 | Please confirm reviewers: |
| 697 | * Approve: "Approved" or "Continue" |
| 698 | * Modify: "Add [name/email]" or "Remove [name/email]" |
| 699 | * Skip: "None" or "Skip reviewers" |
| 700 | ``` |
| 701 | <!-- </example-gate4> --> |
| 702 | |
| 703 | **Wait for user response and capture selections. Proceed to Gate 5.** |
| 704 | |
| 705 | #### Gate 5: Final Summary & Signoff |
| 706 | |
| 707 | 1. Build complete `handoff.md` with all user-confirmed selections. |
| 708 | 2. Present comprehensive summary of everything that will be created. |
| 709 | 3. Request final signoff before executing PR creation. |
| 710 | |
| 711 | <!-- <example-gate5> --> |
| 712 | **Presentation Format**: |
| 713 | |
| 714 | ```markdown |
| 715 | ## ✨ Final Pull Request Summary |
| 716 | |
| 717 | Ready to create your PR with these details: |
| 718 | |
| 719 | **Pull Request**: |
| 720 | * **Title**: [Confirmed title] |
| 721 | * **Source**: [source-branch] → [target-branch] |
| 722 | * **Draft**: [Yes/No] |
| 723 | * **Files**: [count] changed files |
| 724 | |
| 725 | **Work Items** ([count] to link): |
| 726 | * ADO-[ID]: [Title] |
| 727 | [List all confirmed work items] |
| 728 | |
| 729 | **Reviewers** ([count] total): |
| 730 | * [Name] ([email]) - Required |
| 731 | [List all confirmed reviewers] |
| 732 | |
| 733 | 📄 **Planning Files**: `.copilot-tracking/pr/new/[normalized-branch]/` |
| 734 | 📋 **Detailed Plan**: `handoff.md` |
| 735 | |
| 736 | Everything looks good? Reply with: |
| 737 | * **"Create PR"** or **"Approved"** - I'll create the pull request now |
| 738 | * **"Modify [aspect]"** - Make changes before creating |
| 739 | * **"Cancel"** - Stop without creating the PR |
| 740 | ``` |
| 741 | <!-- </example-gate5> --> |
| 742 | |
| 743 | **Wait for explicit "Create PR" or "Approved" confirmation before proceeding to Phase 6.** |
| 744 | |
| 745 | ### Phase 5 Modification Handling |
| 746 | |
| 747 | When user requests modifications at any gate: |
| 748 | |
| 749 | 1. **File Changes** (Gate 1): |
| 750 | * User can request file additions/removals |
| 751 | * Regenerate `pr-reference.xml` if files added/removed via git commands |
| 752 | * Re-run Phase 2 if significant changes |
| 753 | * Return to Gate 1 for re-confirmation |
| 754 | |
| 755 | 2. **Title/Description Changes** (Gate 2): |
| 756 | * Update `pr.md` with user-requested changes |
| 757 | * Log modifications in `planning-log.md` |
| 758 | * Re-present Gate 2 for confirmation |
| 759 | |
| 760 | 3. **Work Item Changes** (Gate 3): |
| 761 | * Add/remove work items from link list |
| 762 | * If user provides new IDs, fetch and validate them |
| 763 | * Update `pr-analysis.md` with confirmed selections |
| 764 | * Re-present Gate 3 for confirmation |
| 765 | |
| 766 | 4. **Reviewer Changes** (Gate 4): |
| 767 | * Add/remove reviewers from list |
| 768 | * Validate email addresses if new reviewers added |
| 769 | * Update `reviewer-analysis.md` with confirmed selections |
| 770 | * Re-present Gate 4 for confirmation |
| 771 | |
| 772 | 5. **Final Changes** (Gate 5): |
| 773 | * Allow modifications to any aspect |
| 774 | * Return to specific gate for that aspect |
| 775 | * Rebuild summary after modifications |
| 776 | |
| 777 | **Iteration Protocol**: |
| 778 | |
| 779 | * Track modification count per gate in `planning-log.md` |
| 780 | * After 3+ iterations on same gate, suggest alternative approach or pause |
| 781 | * Always confirm changes before proceeding |
| 782 | |
| 783 | ### Phase 6 – Create Pull Request & Link Work Items |
| 784 | |
| 785 | **Only proceed after user gives explicit approval.** |
| 786 | |
| 787 | 1. **Resolve Repository and Project IDs**: |
| 788 | * **Repository ID**: If `${input:repository}` is a GUID format, use directly; otherwise: |
| 789 | * Search workspace for repository configuration (`.azure/`, `azure-pipelines.yml`, or project docs) |
| 790 | * Use `mcp_ado_repo_list_pull_requests_by_project` to discover repository ID from project |
| 791 | * If unavailable, ask user to provide repository ID |
| 792 | * **Project ID**: ADO project ID required for work item linking: |
| 793 | * If `${input:adoProject}` is a GUID, use directly |
| 794 | * Otherwise, use `mcp_ado_search_workitem` response metadata to extract project ID |
| 795 | * If unavailable, note work item linking will require manual completion |
| 796 | * Log both IDs in `planning-log.md` |
| 797 | |
| 798 | 2. **Prepare Source and Target Branch References**: |
| 799 | * Source: `refs/heads/${input:sourceBranch}` (or current branch) |
| 800 | * Target: Extract branch name from `${input:baseBranch}` (e.g., `origin/main` → `refs/heads/main`) |
| 801 | |
| 802 | 3. **Create Pull Request**: |
| 803 | * Tool: `mcp_ado_repo_create_pull_request` |
| 804 | * Required parameters: |
| 805 | * `repositoryId`: [Repository ID from step 1] |
| 806 | * `sourceRefName`: [Source ref from step 2] |
| 807 | * `targetRefName`: [Target ref from step 2] |
| 808 | * `title`: [PR title from pr.md with leading # and whitespace removed] |
| 809 | * Optional parameters: |
| 810 | * `description`: [Body of pr.md after first line with full markdown formatting] |
| 811 | * `isDraft`: `${input:isDraft}` |
| 812 | * Capture returned pull request ID and URL |
| 813 | * Log PR creation result in `planning-log.md` |
| 814 | * Update `handoff.md` with actual PR ID and URL |
| 815 | |
| 816 | 4. **Link Work Items** (if any were selected/provided): |
| 817 | * For each work item to link: |
| 818 | * Tool: `mcp_ado_wit_link_work_item_to_pull_request` |
| 819 | * Required parameters: |
| 820 | * `projectId`: [Project ID from step 1 - must be GUID format] |
| 821 | * `repositoryId`: [Repository ID from step 1] |
| 822 | * `pullRequestId`: [PR ID from step 3] |
| 823 | * `workItemId`: [Work item ID to link] |
| 824 | * Log each linking result in `planning-log.md` |
| 825 | * Update `handoff.md` checkbox for each work item |
| 826 | * If project ID unavailable, document work items for manual linking in final recap |
| 827 | |
| 828 | 5. **Add Reviewers** (if any were confirmed and resolved): |
| 829 | * Tool: `mcp_ado_repo_update_pull_request_reviewers` |
| 830 | * Parameters: `repositoryId`, `pullRequestId`, `reviewerIds` (array of GUIDs), `action: "add"` |
| 831 | * **Important**: All reviewers are added as **optional** reviewers by default |
| 832 | * **No-Gates Mode**: If `${input:noGates}` is true, add top 2 reviewers by contribution score (minimum 2 optional reviewers) |
| 833 | * Add all reviewers with resolved identity IDs in a single batch call |
| 834 | * For reviewers without resolved IDs, document in final recap for manual addition via Azure DevOps UI |
| 835 | * Log reviewer addition results in `planning-log.md` |
| 836 | |
| 837 | 6. **Final Validation**: |
| 838 | * Read back `handoff.md` to verify all checkboxes |
| 839 | * Confirm PR URL is accessible |
| 840 | * Verify work item links in Azure DevOps (if possible via tools) |
| 841 | |
| 842 | <!-- <example-mcp-tool-calls> --> |
| 843 | ## MCP Tool Call Examples |
| 844 | |
| 845 | ### Create Pull Request |
| 846 | |
| 847 | ```javascript |
| 848 | mcp_ado_repo_create_pull_request({ |
| 849 | repositoryId: "a1b2c3d4-e5f6-7890-abcd-ef1234567890", |
| 850 | sourceRefName: "refs/heads/feat/acr-dual-access", |
| 851 | targetRefName: "refs/heads/main", |
| 852 | title: "feat(acr): add dual public/private access support", |
| 853 | description: "## Summary\n\nAdds support for dual access patterns...", |
| 854 | isDraft: false |
| 855 | }) |
| 856 | ``` |
| 857 | |
| 858 | ### Link Work Item to Pull Request |
| 859 | |
| 860 | ```javascript |
| 861 | mcp_ado_wit_link_work_item_to_pull_request({ |
| 862 | projectId: "hve-core-project-id", // Must be project ID, not name |
| 863 | repositoryId: "a1b2c3d4-e5f6-7890-abcd-ef1234567890", |
| 864 | pullRequestId: 1234, |
| 865 | workItemId: 5678 |
| 866 | }) |
| 867 | ``` |
| 868 | |
| 869 | ### Resolve Reviewer Identity IDs |
| 870 | |
| 871 | ```javascript |
| 872 | // Resolve single reviewer email to Azure DevOps identity ID |
| 873 | mcp_ado_core_get_identity_ids({ |
| 874 | searchFilter: "sample.name@example.com" |
| 875 | }) |
| 876 | // Returns: [{"id":"d291b0c4-a05c-4ea6-8df1-4b41d5f39eff","displayName":"Sample Name","descriptor":"aad.YTkz..."}] |
| 877 | ``` |
| 878 | |
| 879 | ### Add Reviewers to Pull Request |
| 880 | |
| 881 | ```javascript |
| 882 | // Add multiple reviewers in a single batch call |
| 883 | mcp_ado_repo_update_pull_request_reviewers({ |
| 884 | repositoryId: "a1b2c3d4-e5f6-7890-abcd-ef1234567890", |
| 885 | pullRequestId: 1234, |
| 886 | reviewerIds: [ |
| 887 | "d291b0c4-a05c-4ea6-8df1-4b41d5f39eff", // Sample Name |
| 888 | "f5e6d7c8-b9a0-1234-5678-90abcdef1234" // Another reviewer |
| 889 | ], |
| 890 | action: "add" |
| 891 | }) |
| 892 | ``` |
| 893 | <!-- </example-mcp-tool-calls> --> |
| 894 | |
| 895 | ### Phase 7 – Deliver Final Recap |
| 896 | |
| 897 | Provide conversational summary covering: |
| 898 | |
| 899 | * PR creation status and URL |
| 900 | * Work items linked (count and IDs) |
| 901 | * Reviewers status (added or manual action required) |
| 902 | * Planning workspace location |
| 903 | * Next steps if any |
| 904 | |
| 905 | <!-- <example-final-recap> --> |
| 906 | ```markdown |
| 907 | ## ✅ Pull Request Created Successfully |
| 908 | |
| 909 | **PR Number**: [PR ID number] |
| 910 | **URL**: [PR URL] |
| 911 | **Title**: [PR title] |
| 912 | **Status**: [Active|Draft] |
| 913 | |
| 914 | ### Linked Work Items |
| 915 | * ADO-[ID]: [Title] |
| 916 | * ADO-[ID]: [Title] |
| 917 | |
| 918 | ### Reviewers |
| 919 | * **Required**: [Name] ([email]) |
| 920 | * **Optional**: [Name] ([email]) |
| 921 | * **Note**: Reviewers added automatically or manually via [PR URL] if identity resolution failed |
| 922 | |
| 923 | ### Planning Files |
| 924 | All artifacts saved to: `.copilot-tracking/pr/new/[normalized-branch]/` |
| 925 | |
| 926 | **Next Steps**: |
| 927 | 1. Review the PR at [PR URL] |
| 928 | 2. Add reviewers if not done automatically |
| 929 | 3. Monitor for build status and feedback |
| 930 | ``` |
| 931 | <!-- </example-final-recap> --> |
| 932 | |
| 933 | ## Error Recovery |
| 934 | |
| 935 | * **Phase 1**: PR reference generation fails → verify git state, branch existence, base branch validity |
| 936 | * **Phase 3**: Too many/no work items → adjust similarity threshold or keyword groups; if still none, proceed to Phase 3a to create work item |
| 937 | * **Phase 3a**: Work item creation fails → log error, inform user, proceed to Phase 4 without work item (user can link manually later) |
| 938 | * **Phase 4**: Identity resolution fails → mark reviewer for manual addition via Azure DevOps UI |
| 939 | * **Phase 6**: Repository/Project ID not found → search workspace config or request from user |
| 940 | * **Phase 6**: PR creation fails → verify branch refs, permissions, no duplicate PR |
| 941 | * **Phase 6**: Work item linking fails → verify work item exists, project ID is GUID format, PR created successfully |
| 942 | * **Phase 6**: Reviewer addition fails → provide manual addition instructions with PR URL |
| 943 | |
| 944 | ## Presentation Guidelines |
| 945 | |
| 946 | * Use markdown: **bold** for emphasis, emoji for visual clarity (✅, 📄, 🔍) |
| 947 | * Present summaries before details; avoid information overload |
| 948 | * Provide clear options with suggested responses |
| 949 | * Confirm before irreversible actions |
| 950 | |
| 951 | ## State Persistence & Recovery |
| 952 | |
| 953 | * Maintain `planning-log.md` after each major action |
| 954 | * Update phase transitions in `planning-log.md` |
| 955 | * If context is summarized: |
| 956 | 1. Read all planning files from `.copilot-tracking/pr/new/<normalized-branch>/` |
| 957 | 2. Rebuild context from `planning-log.md` current phase |
| 958 | 3. Resume from last incomplete step |
| 959 | 4. Inform user of recovery process |
| 960 | |
| 961 | ## Repository-Specific Conventions |
| 962 | |
| 963 | When working in this repository: |
| 964 | |
| 965 | * Follow PR description format specified in Phase 2 (pr-file-format block) |
| 966 | * Use conventional commit types in PR titles |
| 967 | * Include component scope when applicable |
| 968 | * Reference changed files for reviewer context |
| 969 | * Link related documentation when available |
| 970 | * Follow markdown linting rules per `.markdownlint.json` |
| 971 | * Use natural, human-friendly language in PR descriptions |
| 972 | * Group changes by significance and importance |
| 973 | * Avoid speculating about benefits not stated in commits |
| 974 | |