microsoft/hve-core
Publicmirrored fromhttps://github.com/microsoft/hve-coreAvailable
docs/agents/github-backlog/discovery.md
127lines · modecode
| 1 | --- |
| 2 | title: Discovery Workflow |
| 3 | description: Discover and categorize GitHub issues through user-centric, artifact-driven, and search-based paths |
| 4 | sidebar_position: 3 |
| 5 | author: Microsoft |
| 6 | ms.date: 2026-02-12 |
| 7 | ms.topic: tutorial |
| 8 | keywords: |
| 9 | - github backlog manager |
| 10 | - issue discovery |
| 11 | - github copilot |
| 12 | estimated_reading_time: 5 |
| 13 | --- |
| 14 | |
| 15 | The Discovery workflow finds and categorizes GitHub issues from multiple sources, producing structured analysis files that feed into triage and planning. |
| 16 | |
| 17 | ## When to Use |
| 18 | |
| 19 | * 🆕 Starting a new sprint and need to survey open issues across repositories |
| 20 | * 👤 Reviewing issues assigned to you or your team before a planning session |
| 21 | * 🔀 Code changes on a feature branch that may relate to existing backlog items |
| 22 | * 🔍 Searching for issues matching specific criteria across multiple repositories |
| 23 | |
| 24 | ## What It Does |
| 25 | |
| 26 | 1. Identifies issues through one of three discovery paths (user-centric, artifact-driven, or search-based) |
| 27 | 2. Retrieves issue metadata including labels, assignees, milestones, and linked pull requests |
| 28 | 3. Categorizes issues by type, area, and current state |
| 29 | 4. Produces structured analysis files with issue summaries and recommendations |
| 30 | 5. Flags issues that may need triage attention (unlabeled, stale, or assigned incorrectly) |
| 31 | |
| 32 | > [!NOTE] |
| 33 | > Discovery is deliberately separated from triage. Finding issues and deciding what to do with them are different cognitive tasks. Running them in a single pass increases the chance of misclassification. |
| 34 | |
| 35 | ## The Three Discovery Paths |
| 36 | |
| 37 | ### User-Centric Discovery |
| 38 | |
| 39 | Finds issues assigned to a specific user or team. This path is ideal for sprint preparation, where you need to see your current backlog before planning new work. The workflow queries GitHub for issues by assignee, filters by state, and organizes results by repository and milestone. |
| 40 | |
| 41 | ### Artifact-Driven Discovery |
| 42 | |
| 43 | Analyzes local code changes (branches, commits, modified files) and maps them to existing backlog items. This path surfaces issues related to your current work, helping you avoid duplicate effort and identify issues your changes may resolve. The workflow reads git diff output and searches for matching issues by file path, keyword, and component area. |
| 44 | |
| 45 | ### Search-Based Discovery |
| 46 | |
| 47 | Queries across repositories using criteria you define: labels, keywords, date ranges, milestone association, or any combination. This path handles broad inventory tasks, such as finding all unlabeled issues, all issues older than 90 days, or all issues in a specific area across multiple repositories. |
| 48 | |
| 49 | ## Output Artifacts |
| 50 | |
| 51 | ```text |
| 52 | .copilot-tracking/github-issues/discovery/<scope-name>/ |
| 53 | ├── issue-analysis.md # Categorized issue inventory with metadata |
| 54 | ├── issues-plan.md # Recommended actions for discovered issues |
| 55 | └── planning-log.md # Discovery session log with search queries used |
| 56 | ``` |
| 57 | |
| 58 | Discovery writes its output to the `.copilot-tracking/github-issues/discovery/` directory. The scope name reflects the discovery target (a username, repository, or search description). These files serve as input for the triage workflow. |
| 59 | |
| 60 | ## How to Use |
| 61 | |
| 62 | ### Option 1: Prompt Shortcut |
| 63 | |
| 64 | Use the backlog manager prompts to start a discovery session: |
| 65 | |
| 66 | ```text |
| 67 | Discover open issues assigned to me in microsoft/hve-core |
| 68 | ``` |
| 69 | |
| 70 | ```text |
| 71 | Find issues related to my current branch changes |
| 72 | ``` |
| 73 | |
| 74 | ```text |
| 75 | Search for unlabeled issues across all repositories in our organization |
| 76 | ``` |
| 77 | |
| 78 | ### Option 2: Direct Agent |
| 79 | |
| 80 | Start a conversation with the GitHub Backlog Manager agent and describe your discovery goal. The agent classifies your intent and dispatches the appropriate discovery path automatically. |
| 81 | |
| 82 | ## Example Prompt |
| 83 | |
| 84 | ```text |
| 85 | Discover open issues assigned to me in microsoft/hve-core that don't have |
| 86 | a milestone. Include any issues labeled "needs-triage" regardless of assignee. |
| 87 | ``` |
| 88 | |
| 89 | ## Tips |
| 90 | |
| 91 | ✅ Do: |
| 92 | |
| 93 | * Scope discovery to a specific repository or user to keep results manageable |
| 94 | * Run discovery before triage to ensure you have a complete picture |
| 95 | * Use artifact-driven discovery when working on a feature branch to find related issues |
| 96 | * Review the planning log to understand what queries produced the results |
| 97 | |
| 98 | ❌ Don't: |
| 99 | |
| 100 | * Combine discovery with triage in a single session (clear context between workflows) |
| 101 | * Run discovery across an entire organization without filters (results become unwieldy) |
| 102 | * Skip reviewing the issue analysis before proceeding to triage |
| 103 | * Assume discovery catches everything on the first pass (iterate if needed) |
| 104 | |
| 105 | ## Common Pitfalls |
| 106 | |
| 107 | | Pitfall | Solution | |
| 108 | |------------------------------------------|-----------------------------------------------------------------------| |
| 109 | | Too many results to review | Narrow the scope with repository, label, or date filters | |
| 110 | | Missing issues from private repositories | Verify MCP token has access to the target repositories | |
| 111 | | Stale results from cached queries | Clear context and re-run discovery for fresh API results | |
| 112 | | Artifact-driven path finds no matches | Ensure your branch has committed changes (unstaged files are skipped) | |
| 113 | |
| 114 | ## Next Steps |
| 115 | |
| 116 | 1. Send your discovery output through the [Triage workflow](triage.md) to assign labels and priorities |
| 117 | 2. See [Using Workflows Together](using-together.md) for the full pipeline walkthrough |
| 118 | |
| 119 | > [!TIP] |
| 120 | > Run `/clear` between discovery and triage. Each workflow reads its own planning files and mixing session context produces unreliable label suggestions. |
| 121 | |
| 122 | --- |
| 123 | |
| 124 | <!-- markdownlint-disable MD036 --> |
| 125 | *🤖 Crafted with precision by ✨Copilot following brilliant human instruction, |
| 126 | then carefully refined by our team of discerning human reviewers.* |
| 127 | <!-- markdownlint-enable MD036 --> |
| 128 | |