microsoft/hve-core
Publicmirrored fromhttps://github.com/microsoft/hve-coreAvailable
.github/instructions/github/github-backlog-triage.instructions.md
302lines · modecode
| 1 | --- |
| 2 | description: 'Triage workflow for GitHub issue backlog management - automated label suggestion, milestone assignment, and duplicate detection' |
| 3 | applyTo: '**/.copilot-tracking/github-issues/triage/**' |
| 4 | --- |
| 5 | |
| 6 | # GitHub Backlog Triage Instructions |
| 7 | |
| 8 | ## Purpose and Scope |
| 9 | |
| 10 | This workflow analyzes untriaged GitHub issues, suggests labels based on conventional commit title patterns, assigns milestones using the repository's discovered versioning strategy, and detects duplicates through similarity assessment. |
| 11 | |
| 12 | Follow all instructions from #file:./github-backlog-planning.instructions.md while executing this workflow. |
| 13 | |
| 14 | Follow community interaction guidelines from #file:./community-interaction.instructions.md when posting comments visible to external contributors. |
| 15 | |
| 16 | ## Autonomy Behavior for Triage Operations |
| 17 | |
| 18 | | Operation | Full | Partial | Manual | |
| 19 | |-----------------------------------|--------------|--------------|--------------| |
| 20 | | Label assignment | Auto-execute | Auto-execute | Gate on user | |
| 21 | | Milestone assignment | Auto-execute | Auto-execute | Gate on user | |
| 22 | | Duplicate closure | Auto-execute | Gate on user | Gate on user | |
| 23 | | needs-triage removal (classified) | Auto-execute | Auto-execute | Gate on user | |
| 24 | |
| 25 | Unclassified issues (titles without a recognized conventional commit pattern) retain `needs-triage` across all autonomy tiers. Label and milestone suggestions still apply, but `needs-triage` is not removed. |
| 26 | |
| 27 | ## Required Phases |
| 28 | |
| 29 | ### Phase 1: Analyze |
| 30 | |
| 31 | Fetch and analyze untriaged issues to build a comprehensive triage assessment. Proceed to Phase 2 when all fetched issues have been analyzed and recorded. |
| 32 | |
| 33 | #### Step 1: Discover Available Milestones |
| 34 | |
| 35 | Before analyzing issues, discover the repository's milestone strategy. When `milestone` is provided as an override, skip this step and use that value. |
| 36 | |
| 37 | 1. Invoke the milestone discovery protocol defined in the Milestone Discovery Protocol section of `github-backlog-planning.instructions.md` to fetch, classify, and build the milestone assignment map. |
| 38 | 2. Record the detected naming pattern, per-milestone role classification, and generated assignment map in planning-log.md. |
| 39 | 3. When discovery confidence is low, attempt to load `.github/milestone-strategy.yml` as an optional override; if the file is not present or does not define a clear strategy, prompt the user before proceeding. |
| 40 | |
| 41 | When milestone discovery yields no results, prompt the user for milestone names before proceeding. |
| 42 | |
| 43 | #### Step 2: Fetch Untriaged Issues |
| 44 | |
| 45 | Search for issues carrying the `needs-triage` label using `mcp_github_search_issues` with the following query pattern: |
| 46 | |
| 47 | ```text |
| 48 | repo:{owner}/{repo} is:issue is:open label:needs-triage |
| 49 | ``` |
| 50 | |
| 51 | Paginate results using `perPage` and `page` parameters, limiting to `maxIssues` total issues. |
| 52 | |
| 53 | When no untriaged issues are found, inform the user and end the workflow. No further phases apply. |
| 54 | |
| 55 | #### Step 3: Hydrate Issue Details |
| 56 | |
| 57 | For each returned issue, fetch full details using `mcp_github_issue_read` with `method: 'get'` to retrieve body content, existing labels, and current milestone. Also fetch current labels using `mcp_github_issue_read` with `method: 'get_labels'` to capture the complete label set for each issue. |
| 58 | |
| 59 | #### Step 4: Analyze Each Issue |
| 60 | |
| 61 | For each untriaged issue, perform the following analysis: |
| 62 | |
| 63 | 1. Parse the title against the conventional commit title pattern mapping table to determine suggested type labels. |
| 64 | 2. Extract scope keywords from `type(scope):` patterns and map them to scope labels. Scope extraction applies to all conventional commit types, not only specific patterns. |
| 65 | 3. Examine the body content for additional context: |
| 66 | * Identify scope indicators not captured by the title pattern (file paths, directory references, component names). |
| 67 | * Note acceptance criteria that inform priority assessment. |
| 68 | * Extract technical context that clarifies issue intent for similarity comparison. |
| 69 | 4. Review existing labels for conflicts or gaps (for example, an issue labeled `enhancement` with a `fix:` title prefix). |
| 70 | 5. Search for potential duplicates using the similarity assessment framework per templates in the planning specification. |
| 71 | 6. Evaluate milestone fit based on the discovered milestone strategy and the priority assessment criteria defined in this file. |
| 72 | |
| 73 | #### Step 5: Record Analysis |
| 74 | |
| 75 | Create planning-log.md in `.copilot-tracking/github-issues/triage/{{YYYY-MM-DD}}/` to track progress. Update the log as each issue is analyzed, recording: |
| 76 | |
| 77 | * Issue number and title |
| 78 | * Current labels (from hydration) |
| 79 | * Suggested labels with rationale |
| 80 | * Suggested milestone with rationale |
| 81 | * Duplicate candidates with similarity category |
| 82 | * Priority assessment result |
| 83 | |
| 84 | ### Phase 2: Plan |
| 85 | |
| 86 | Produce a triage plan for user review and execute confirmed recommendations. This phase completes when all confirmed recommendations have been applied and planning-log.md reflects final state. |
| 87 | |
| 88 | #### Step 1: Generate Triage Plan |
| 89 | |
| 90 | Create triage-plan.md in `.copilot-tracking/github-issues/triage/{{YYYY-MM-DD}}/` with a recommendation row per issue. Use the triage plan template defined in the Output section of this file. |
| 91 | |
| 92 | #### Step 2: Present for Review |
| 93 | |
| 94 | Present the triage plan to the user, highlighting: |
| 95 | |
| 96 | * Issues with high-confidence label and milestone suggestions |
| 97 | * Issues flagged as potential duplicates |
| 98 | * Issues requiring manual review (ambiguous titles, conflicting labels, uncertain similarity) |
| 99 | |
| 100 | When `autonomy` is `full`, proceed directly to Step 3 without waiting for user confirmation. When `partial`, gate on duplicate closures only. When `manual`, wait for user confirmation of the entire plan. |
| 101 | |
| 102 | #### Step 3: Execute Confirmed Recommendations |
| 103 | |
| 104 | On user confirmation (or immediately under full autonomy), apply the approved recommendations. Before composing any content for a GitHub API call, apply the Content Sanitization Guards from #file:./github-backlog-planning.instructions.md. |
| 105 | |
| 106 | For classified non-duplicate issues (title matched a recognized conventional commit pattern), consolidate label assignment, milestone assignment, and `needs-triage` removal into a single API call per issue: |
| 107 | |
| 108 | 1. Compute the new label set: `(current_labels - "needs-triage") + suggested_labels`. |
| 109 | 2. Call `mcp_github_issue_write` with `method: 'update'`, `labels: [computed_set]`, and `milestone: suggested_milestone`. |
| 110 | |
| 111 | The `labels` parameter uses replacement semantics. The computed set must include all labels to retain, all suggested labels to add, and must exclude `needs-triage`. |
| 112 | |
| 113 | For unclassified non-duplicate issues (title did not match any recognized pattern), apply suggested labels while retaining `needs-triage`: |
| 114 | |
| 115 | 1. Compute the new label set: `current_labels + suggested_labels`. |
| 116 | 2. Call `mcp_github_issue_write` with `method: 'update'`, `labels: [computed_set]`, and `milestone: suggested_milestone`. |
| 117 | |
| 118 | The `labels` parameter uses replacement semantics. The computed set must include all existing labels (including `needs-triage`), plus any suggested labels. |
| 119 | |
| 120 | For confirmed duplicates, apply the comment-before-closure pattern: |
| 121 | |
| 122 | 1. Post a comment using `mcp_github_add_issue_comment` with the Scenario 7 (Closing a Duplicate Issue) template from `community-interaction.instructions.md`, filling `{{original_number}}` with the matched issue number. |
| 123 | 2. Close the issue using `mcp_github_issue_write` with `method: 'update'`, `state: 'closed'`, `state_reason: 'duplicate'`, and `duplicate_of` set to the original issue number. |
| 124 | |
| 125 | For linked pull requests, propagate the milestone assignment to each associated PR: |
| 126 | |
| 127 | 1. Search for PRs referencing the issue by calling `mcp_github_search_pull_requests` with query `repo:{owner}/{repo} {issue_number}` to find PRs that mention the issue number in their title or body. |
| 128 | 2. Inspect the issue body and comments via `mcp_github_issue_read` with `method: 'get'` and `method: 'get_comments'` for PR references (GitHub PR URLs or `#N` cross-references) that the search may have missed. |
| 129 | 3. For each discovered PR missing the target milestone, call `mcp_github_issue_write` with `method: 'update'`, passing the PR number as `issue_number` and `milestone: suggested_milestone`. |
| 130 | |
| 131 | The Issues API accepts PR numbers because GitHub treats pull requests as a superset of issues sharing the same number space (see the Pull Request Field Operations section in the planning specification). |
| 132 | |
| 133 | Group issues by suggested label when multiple issues share the same recommendation to maintain batch efficiency. Update planning-log.md checkboxes as each operation completes. |
| 134 | |
| 135 | ## Conventional Commit Title Pattern to Label Mapping |
| 136 | |
| 137 | When issue titles follow conventional commit format, map patterns to labels using this table. |
| 138 | |
| 139 | | Title Pattern | Suggested Labels | Description | |
| 140 | |----------------------------------|---------------------------------|-------------------------| |
| 141 | | `feat:` or `feat(scope):` | `feature` | New functionality | |
| 142 | | `fix:` or `fix(scope):` | `bug` | Bug fix | |
| 143 | | `docs:` or `docs(scope):` | `documentation` | Documentation change | |
| 144 | | `chore:` or `chore(scope):` | `maintenance` | Maintenance task | |
| 145 | | `refactor:` | `maintenance` | Code refactoring | |
| 146 | | `test:` | `maintenance` | Test changes | |
| 147 | | `ci:` | `maintenance`, `infrastructure` | CI/CD changes | |
| 148 | | `perf:` | `enhancement` | Performance improvement | |
| 149 | | `style:` | `maintenance` | Code style changes | |
| 150 | | `build:` | `infrastructure` | Build system changes | |
| 151 | | `security:` | `security` | Security fix | |
| 152 | | `breaking:` or `BREAKING CHANGE` | `breaking-change` | Breaking change | |
| 153 | |
| 154 | When a title does not match any conventional commit pattern, retain the `needs-triage` label and flag the issue for manual review. |
| 155 | |
| 156 | ## Scope Keyword to Scope Label Mapping |
| 157 | |
| 158 | Extract scope keywords from the conventional commit title pattern `type(scope):` and map them to scope labels. |
| 159 | |
| 160 | | Scope Keyword | Scope Label | |
| 161 | |------------------|----------------| |
| 162 | | `(agents)` | `agents` | |
| 163 | | `(prompts)` | `prompts` | |
| 164 | | `(instructions)` | `instructions` | |
| 165 | |
| 166 | Additional scope keywords may be mapped when they align with the label taxonomy defined in the planning specification. Scope keywords not present in the taxonomy (for example, `scripts`, `ci`, `workflows`, `templates`) should be noted in the analysis log as body context rather than assigned as labels. |
| 167 | |
| 168 | ## Milestone Recommendation |
| 169 | |
| 170 | Milestone assignment follows the versioning strategy discovered during Phase 1, Step 1. Apply these recommendations based on issue characteristics. |
| 171 | |
| 172 | | Issue Characteristic | Stability Target | Proximity Target | Rationale | |
| 173 | |----------------------------|------------------|------------------|-----------------------------------------------------| |
| 174 | | Bug fix | stable | current | Production fixes target the nearest stable release | |
| 175 | | Security fix | stable | current | Security patches ship in the nearest stable release | |
| 176 | | Maintenance or refactoring | stable | current | Low-risk changes target stable releases | |
| 177 | | Documentation improvement | stable | current | Documentation ships with stable releases | |
| 178 | | New feature | pre-release | next | Features incubate before stable release | |
| 179 | | Breaking change | pre-release | next | Breaking changes land in development milestones | |
| 180 | | Infrastructure improvement | stable | current | CI/CD and build changes target stable releases | |
| 181 | |
| 182 | When uncertain about milestone assignment, default to the nearest pre-release or next milestone and flag the issue for human review. |
| 183 | |
| 184 | ## Duplicate Detection |
| 185 | |
| 186 | For each untriaged issue, search for potential duplicates using the similarity assessment framework from the planning specification. |
| 187 | |
| 188 | ### Search Strategy |
| 189 | |
| 190 | Build search queries from the issue title and body: |
| 191 | |
| 192 | 1. Extract 2-4 keyword groups from the issue title. |
| 193 | 2. Execute `mcp_github_search_issues` for each keyword group scoped to the repository. |
| 194 | 3. Assess similarity of returned results against the untriaged issue using the assessment template from the planning specification. |
| 195 | |
| 196 | ### Duplicate Resolution |
| 197 | |
| 198 | | Similarity Category | Action | |
| 199 | |---------------------|------------------------------------------------------------------------------------| |
| 200 | | Match | Suggest closing the untriaged issue as duplicate with a reference to the original. | |
| 201 | | Similar | Flag both issues for user review with a comparison summary. | |
| 202 | | Distinct | Proceed with label and milestone assignment. | |
| 203 | | Uncertain | Request user guidance before taking action. | |
| 204 | |
| 205 | When a Match is found, record the original issue number in the triage plan for the `duplicate_of` field. The Close operation must include `state_reason: 'duplicate'` per the issue field matrix in the planning specification. |
| 206 | |
| 207 | Duplicate closure follows the comment-before-closure pattern: |
| 208 | |
| 209 | 1. Post a comment using `mcp_github_add_issue_comment` with the Scenario 7 (Closing a Duplicate Issue) template from `community-interaction.instructions.md`, filling `{{original_number}}` with the matched issue number. |
| 210 | 2. Close the issue using `mcp_github_issue_write` with `method: 'update'`, `state: 'closed'`, `state_reason: 'duplicate'`, and `duplicate_of` set to the original issue number. |
| 211 | |
| 212 | ## Priority Assessment |
| 213 | |
| 214 | Assess priority based on the suggested label to determine triage ordering. Process higher-priority issues first. |
| 215 | |
| 216 | | Priority | Label(s) | Handling | |
| 217 | |----------|--------------------------------|----------------------------------------------------------------------------------------------------------| |
| 218 | | Highest | `security` | Flag for immediate attention. Assign to the nearest stable or current milestone with expedited notation. | |
| 219 | | High | `bug` | Assign to the nearest stable or current milestone. Prioritize in triage plan. | |
| 220 | | Normal | `feature`, `enhancement` | Assign to the appropriate milestone per the discovered strategy. | |
| 221 | | Lower | `documentation`, `maintenance` | Assign to the nearest stable or current milestone. Process after higher-priority items. | |
| 222 | |
| 223 | Issues with the `breaking-change` label are escalated to the nearest pre-release or next milestone regardless of other priority signals. Under partial and manual autonomy, flag `breaking-change` issues for human review before applying milestone assignment, consistent with the Human Review Triggers in the planning specification. |
| 224 | |
| 225 | ## Error Handling |
| 226 | |
| 227 | Handle API failures and edge cases during triage execution: |
| 228 | |
| 229 | * When a label or milestone update fails due to rate limiting, log the failure in planning-log.md and retry after the rate limit window resets. Continue processing remaining issues. |
| 230 | * When `mcp_github_issue_write` returns a validation error (for example, an invalid milestone name), log the error, skip the affected issue, and flag it for manual review in the triage plan. |
| 231 | * When `mcp_github_search_issues` returns no results for a duplicate search query, record "no duplicates found" and proceed with label and milestone assignment. |
| 232 | * When an issue has been modified between analysis and execution (labels or state changed externally), re-fetch the issue details before applying updates to avoid overwriting concurrent changes. |
| 233 | * When the comment step of a comment-before-closure pattern fails, log the failure in planning-log.md and proceed with the closure call. The closure carries the authoritative state change; the comment provides contributor context. |
| 234 | |
| 235 | ## Output |
| 236 | |
| 237 | The triage workflow produces output files in `.copilot-tracking/github-issues/triage/{{YYYY-MM-DD}}/`. |
| 238 | |
| 239 | ### triage-plan.md Template |
| 240 | |
| 241 | Planning markdown files must start and end with the directives defined in the planning specification. |
| 242 | |
| 243 | ```markdown |
| 244 | <!-- markdownlint-disable-file --> |
| 245 | <!-- markdown-table-prettify-ignore-start --> |
| 246 | # Triage Plan - {{YYYY-MM-DD}} |
| 247 | |
| 248 | * **Repository**: {{owner}}/{{repo}} |
| 249 | * **Issues Analyzed**: {{count}} |
| 250 | * **Date**: {{YYYY-MM-DD}} |
| 251 | |
| 252 | ## Summary |
| 253 | |
| 254 | | Action | Count | |
| 255 | | --------------- | ------------------ | |
| 256 | | Label + Assign | {{label_count}} | |
| 257 | | Close Duplicate | {{duplicate_count}} | |
| 258 | | Manual Review | {{review_count}} | |
| 259 | |
| 260 | ## Triage Recommendations |
| 261 | |
| 262 | | Issue | Title | Suggested Labels | Suggested Milestone | Duplicates Found | Priority | Action | |
| 263 | | ----- | ----- | ---------------- | ------------------- | ---------------- | -------- | ------ | |
| 264 | | #{{number}} | {{title}} | {{labels}} | {{milestone}} | {{duplicate_refs}} | {{priority}} | {{action}} | |
| 265 | |
| 266 | ## Issues Requiring Manual Review |
| 267 | |
| 268 | ### #{{number}}: {{title}} |
| 269 | |
| 270 | * **Reason**: {{reason for manual review}} |
| 271 | * **Current Labels**: {{existing_labels}} |
| 272 | * **Suggested Labels**: {{suggested_labels}} |
| 273 | * **Notes**: {{additional context}} |
| 274 | |
| 275 | ## Duplicate Pairs |
| 276 | |
| 277 | ### #{{untriaged_number}} duplicates #{{original_number}} |
| 278 | |
| 279 | * **Similarity Category**: Match |
| 280 | * **Rationale**: {{explanation}} |
| 281 | * **Recommended Action**: Close #{{untriaged_number}} as duplicate of #{{original_number}} |
| 282 | <!-- markdown-table-prettify-ignore-end --> |
| 283 | ``` |
| 284 | |
| 285 | ### planning-log.md |
| 286 | |
| 287 | Use the planning-log.md template from the planning specification. Set the planning type to `Triage` and track each issue through analysis, planning, and execution. |
| 288 | |
| 289 | ## Success Criteria |
| 290 | |
| 291 | Triage is complete when: |
| 292 | |
| 293 | * All fetched issues (up to `maxIssues`) with the `needs-triage` label have been analyzed for label suggestions, milestone recommendations, and duplicate candidates. |
| 294 | * A triage-plan.md exists with a recommendation row for every analyzed issue. |
| 295 | * The user has reviewed and confirmed (or adjusted) the triage plan, respecting the active autonomy tier. |
| 296 | * Confirmed recommendations have been executed via consolidated API calls (labels assigned, milestones set, `needs-triage` removed from classified issues, duplicates closed). |
| 297 | * planning-log.md reflects the final state of all operations with checkboxes marking completion. |
| 298 | * Any failed operations have been logged and either retried or flagged for manual follow-up. |
| 299 | |
| 300 | --- |
| 301 | |
| 302 | Brought to you by microsoft/hve-core |
| 303 | |