microsoft/hve-core
Publicmirrored fromhttps://github.com/microsoft/hve-coreAvailable
docs/agents/github-backlog/triage.md
132lines · modecode
| 1 | --- |
| 2 | title: Triage Workflow |
| 3 | description: Classify, label, and detect duplicate GitHub issues using structured triage analysis |
| 4 | author: Microsoft |
| 5 | ms.date: 2026-02-12 |
| 6 | ms.topic: tutorial |
| 7 | keywords: |
| 8 | - github backlog manager |
| 9 | - issue triage |
| 10 | - labels |
| 11 | - duplicate detection |
| 12 | - github copilot |
| 13 | estimated_reading_time: 5 |
| 14 | --- |
| 15 | |
| 16 | The Triage workflow classifies issues discovered in the previous phase, recommending labels, detecting duplicates, and producing handoff files for sprint planning or direct execution. |
| 17 | |
| 18 | ## When to Use |
| 19 | |
| 20 | * 🏷️ Issues need labels assigned or updated after a discovery pass |
| 21 | * 🔁 Suspected duplicates require confirmation before closing |
| 22 | * 📊 Preparing issue metadata for milestone assignment in sprint planning |
| 23 | * 🧹 Cleaning up a backlog with inconsistent or missing labels |
| 24 | |
| 25 | ## What It Does |
| 26 | |
| 27 | 1. Reads issue analysis files produced by the discovery workflow |
| 28 | 2. Evaluates each issue against a 17-label taxonomy organized by category |
| 29 | 3. Compares issues across four similarity dimensions to detect duplicates |
| 30 | 4. Generates confidence scores for label suggestions and duplicate matches |
| 31 | 5. Produces triage recommendations with reasoning for each classification |
| 32 | |
| 33 | > [!NOTE] |
| 34 | > Triage recommendations are proposals, not automatic changes. The execution workflow applies labels and closes duplicates only after you review and approve the handoff file. |
| 35 | |
| 36 | ## Label Taxonomy |
| 37 | |
| 38 | The triage workflow uses a structured label taxonomy organized into four categories: |
| 39 | |
| 40 | | Category | Labels | Purpose | |
| 41 | |-----------|-----------------------------------------------------------------|------------------------------------| |
| 42 | | Type | bug, feature, enhancement, documentation, maintenance, security | Classifies the nature of work | |
| 43 | | Lifecycle | needs-triage, duplicate, wontfix, breaking-change | Controls issue disposition | |
| 44 | | Scope | agents, prompts, instructions, infrastructure | Maps to repository components | |
| 45 | | Community | good-first-issue, help-wanted, question | Contributor engagement and support | |
| 46 | |
| 47 | Each issue receives one label per category where applicable. The triage workflow explains its reasoning for each suggested label, allowing you to adjust before execution. |
| 48 | |
| 49 | ## Duplicate Detection |
| 50 | |
| 51 | Duplicate detection compares issues across four dimensions: |
| 52 | |
| 53 | * Title similarity using normalized keyword matching |
| 54 | * Description overlap through content comparison |
| 55 | * Label set intersection to identify functionally equivalent issues |
| 56 | * Assignee and milestone alignment to catch split work items |
| 57 | |
| 58 | When confidence exceeds the threshold, the workflow links the duplicate pair in its recommendation file and suggests which issue to keep based on age, completeness, and discussion activity. |
| 59 | |
| 60 | ## Output Artifacts |
| 61 | |
| 62 | ```text |
| 63 | .copilot-tracking/github-issues/triage/<YYYY-MM-DD>/ |
| 64 | ├── planning-log.md # Progress tracking and analysis results |
| 65 | └── triage-plan.md # Label suggestions, duplicate findings, and recommended operations |
| 66 | ``` |
| 67 | |
| 68 | The triage plan includes reasoning for each classification, making it possible to adjust recommendations before execution applies them. |
| 69 | |
| 70 | ## How to Use |
| 71 | |
| 72 | ### Option 1: Prompt Shortcut |
| 73 | |
| 74 | ```text |
| 75 | Triage the issues discovered in my latest discovery session |
| 76 | ``` |
| 77 | |
| 78 | ```text |
| 79 | Check for duplicates in microsoft/hve-core issues labeled "needs-triage" |
| 80 | ``` |
| 81 | |
| 82 | ### Option 2: Direct Agent |
| 83 | |
| 84 | Attach or reference the discovery output files when starting a triage conversation. The agent reads the issue analysis and begins classification automatically. |
| 85 | |
| 86 | ## Example Prompt |
| 87 | |
| 88 | ```text |
| 89 | Triage all issues from my latest discovery pass for microsoft/hve-core. |
| 90 | Apply the standard label taxonomy and flag any potential duplicates with |
| 91 | confidence scores above 70%. |
| 92 | ``` |
| 93 | |
| 94 | ## Tips |
| 95 | |
| 96 | ✅ Do: |
| 97 | |
| 98 | * Run discovery first to build a complete issue inventory before you triage |
| 99 | * Review duplicate pairs before approving closure recommendations |
| 100 | * Adjust label suggestions in the handoff file before passing to execution |
| 101 | * Use the confidence scores to prioritize which recommendations to review first |
| 102 | |
| 103 | ❌ Don't: |
| 104 | |
| 105 | * Triage issues you haven't discovered (the workflow needs analysis files as input) |
| 106 | * Auto-approve all triage recommendations without reviewing confidence scores |
| 107 | * Modify the handoff file format (execution depends on the checkbox structure) |
| 108 | * Run triage and execution in the same session without clearing context |
| 109 | |
| 110 | ## Common Pitfalls |
| 111 | |
| 112 | | Pitfall | Solution | |
| 113 | |---------------------------------------|-----------------------------------------------------------------------------| |
| 114 | | Low confidence on label suggestions | Provide more context in the issue description or add manual labels | |
| 115 | | False-positive duplicate matches | Review the four similarity dimensions and adjust the confidence threshold | |
| 116 | | Missing labels from taxonomy | Verify the label exists in the repository before expecting triage to use it | |
| 117 | | Triage conflicts with existing labels | The workflow flags conflicts rather than overwriting existing labels | |
| 118 | |
| 119 | ## Next Steps |
| 120 | |
| 121 | 1. Review and adjust the triage handoff file before proceeding |
| 122 | 2. Move to [Sprint Planning](sprint-planning.md) to assign milestones, or skip directly to [Execution](execution.md) for label-only changes |
| 123 | |
| 124 | > [!TIP] |
| 125 | > For repositories with custom label schemes, update the taxonomy reference before running triage. The workflow applies whatever taxonomy is configured, so mismatches produce irrelevant suggestions. |
| 126 | |
| 127 | --- |
| 128 | |
| 129 | <!-- markdownlint-disable MD036 --> |
| 130 | *🤖 Crafted with precision by ✨Copilot following brilliant human instruction, |
| 131 | then carefully refined by our team of discerning human reviewers.* |
| 132 | <!-- markdownlint-enable MD036 --> |