microsoft/hve-core
Publicmirrored fromhttps://github.com/microsoft/hve-coreAvailable
.github/instructions/github/github-backlog-discovery.instructions.md
227lines · modecode
| 1 | --- |
| 2 | description: 'Discovery protocol for GitHub backlog management - artifact-driven, user-centric, and search-based issue discovery' |
| 3 | applyTo: '**/.copilot-tracking/github-issues/discovery/**' |
| 4 | --- |
| 5 | |
| 6 | # GitHub Backlog Discovery |
| 7 | |
| 8 | Discover GitHub issues through three paths: user-centric queries, artifact-driven analysis, or search-based exploration. Follow *github-backlog-planning.instructions.md* for templates, field definitions, and search protocols. |
| 9 | |
| 10 | ## Scope |
| 11 | |
| 12 | Discovery path selection: |
| 13 | |
| 14 | * User-centric (Path A): User requests their issues, assigned work, or milestone progress without referencing artifacts |
| 15 | * Artifact-driven (Path B): Documents, PRDs, or requirements provided for translation into issues |
| 16 | * Search-based (Path C): User provides search terms directly without artifacts or assignment context |
| 17 | |
| 18 | Output location: `.copilot-tracking/github-issues/discovery/<scope-name>/` where `<scope-name>` is a descriptive kebab-case slug derived from the discovery context (for example, `v2-features` or `security-audit`). |
| 19 | |
| 20 | ## Deliverables |
| 21 | |
| 22 | | File | Path A | Path B | Path C | |
| 23 | |------------------------|--------|--------|--------| |
| 24 | | *planning-log.md* | Yes | Yes | Yes | |
| 25 | | *issue-analysis.md* | No | Yes | No | |
| 26 | | *issues-plan.md* | No | Yes | No | |
| 27 | | *handoff.md* | No | Yes | No | |
| 28 | | Conversational summary | Yes | Yes | Yes | |
| 29 | |
| 30 | Paths A and C produce a conversational summary with counts and relevant issue links. Path B produces the full set of planning files per templates in *github-backlog-planning.instructions.md*. |
| 31 | |
| 32 | ## Tooling |
| 33 | |
| 34 | User-centric discovery (Path A): |
| 35 | |
| 36 | * `mcp_github_get_me`: Retrieve authenticated user details for assignee-based queries |
| 37 | * `mcp_github_search_issues`: Search with `assignee:` qualifier scoped to `repo:{owner}/{repo}` |
| 38 | * Key params: `query` (required), `owner`, `repo`, `perPage`, `page` |
| 39 | * `mcp_github_issue_read`: Hydrate results with `method: 'get'` for full details |
| 40 | * When `includeSubIssues` is true, also call with `method: 'get_sub_issues'` |
| 41 | |
| 42 | Artifact-driven discovery (Path B): |
| 43 | |
| 44 | * `read_file`, `grep_search`: Read and parse source documents |
| 45 | * `mcp_github_get_me`: Verify access to the target repository |
| 46 | * `mcp_github_search_issues`: Execute keyword-group queries per the Search Protocol in *github-backlog-planning.instructions.md* |
| 47 | * `mcp_github_issue_read`: Hydrate results and fetch sub-issues when enabled |
| 48 | * `mcp_github_list_issue_types`: Retrieve valid issue types when the organization supports them |
| 49 | |
| 50 | Search-based discovery (Path C): |
| 51 | |
| 52 | * `mcp_github_search_issues`: Execute user-provided terms scoped to `repo:{owner}/{repo}` |
| 53 | * `mcp_github_issue_read`: Hydrate results with `method: 'get'` for full details |
| 54 | |
| 55 | Workspace utilities: `list_dir`, `read_file`, `semantic_search` for artifact location and context gathering. |
| 56 | |
| 57 | ## Required Phases |
| 58 | |
| 59 | ### Phase 1: Discover Issues |
| 60 | |
| 61 | Select the appropriate discovery path based on user intent and available inputs. |
| 62 | |
| 63 | #### Path A: User-Centric Discovery |
| 64 | |
| 65 | Use when: |
| 66 | |
| 67 | * User requests "show me my issues", "what's assigned to me", or similar |
| 68 | * User asks about issues for a specific milestone or label scope |
| 69 | * No artifacts or documents are referenced |
| 70 | |
| 71 | Execution: |
| 72 | |
| 73 | 1. Call `mcp_github_get_me` to determine the authenticated user. |
| 74 | 2. Build a search query with `repo:{owner}/{repo} is:issue assignee:{username}`. Apply `milestone:` and `label:` qualifiers when `milestone` or label context is provided. |
| 75 | 3. Execute `mcp_github_search_issues` and paginate until all results are retrieved. |
| 76 | 4. Hydrate each result via `mcp_github_issue_read` with `method: 'get'`. When `includeSubIssues` is true, also fetch sub-issues. |
| 77 | 5. Present results grouped by state and labels. |
| 78 | 6. Create the planning folder at `.copilot-tracking/github-issues/discovery/<scope-name>/` and initialize *planning-log.md*. |
| 79 | 7. Log discovered issues in *planning-log.md* and deliver a conversational summary. |
| 80 | 8. Skip Phases 2-3; no additional planning files beyond *planning-log.md* are required for user-centric discovery. |
| 81 | |
| 82 | #### Path B: Artifact-Driven Discovery |
| 83 | |
| 84 | Use when: |
| 85 | |
| 86 | * Documents, PRDs, or requirements are provided via `documents` or conversation |
| 87 | * User explicitly requests issue creation or updates from artifacts |
| 88 | |
| 89 | Skip conditions: |
| 90 | |
| 91 | * No artifacts or documents are available; use Path A or Path C instead |
| 92 | |
| 93 | Execution: |
| 94 | |
| 95 | 1. Create the planning folder at `.copilot-tracking/github-issues/discovery/<scope-name>/`. |
| 96 | 2. Call `mcp_github_get_me` to verify repository access. When the organization supports issue types, call `mcp_github_list_issue_types` with the `owner` parameter. |
| 97 | 3. Read each document to completion and extract discrete requirements, acceptance criteria, and action items using the document parsing guidelines in this file. |
| 98 | 4. Record each extracted requirement as a candidate issue entry in *issue-analysis.md* with: temporary ID, suggested title in conventional commit format, body summary, suggested labels, suggested milestone, and source reference. |
| 99 | 5. Build keyword groups from extracted requirements per the Search Protocol in *github-backlog-planning.instructions.md*. |
| 100 | 6. Compose GitHub search queries scoped to `repo:{owner}/{repo}`. Apply `milestone:` qualifier when `milestone` is provided. |
| 101 | 7. Execute `mcp_github_search_issues` for each keyword group and paginate results. |
| 102 | 8. Hydrate each result via `mcp_github_issue_read` with `method: 'get'`. When `includeSubIssues` is true, also fetch sub-issues. |
| 103 | 9. Assess similarity between each fetched issue and the candidate set using the Similarity Assessment Framework in *github-backlog-planning.instructions.md*. Classify each pair as Match, Similar, Distinct, or Uncertain. |
| 104 | 10. De-duplicate results across keyword groups; retain the highest similarity category when the same issue appears in multiple searches. |
| 105 | 11. Log all progress in *planning-log.md* with search queries, result counts, and similarity assessments. |
| 106 | 12. Continue to Phase 2. |
| 107 | |
| 108 | ##### Document Parsing Guidelines |
| 109 | |
| 110 | Map document types and content patterns to issue attributes. |
| 111 | |
| 112 | | Document Type | Content Pattern | Suggested Label | Issue Type | |
| 113 | |---------------|---------------------------|-------------------|-------------| |
| 114 | | PRD | Feature requirement | `feature` | Feature | |
| 115 | | PRD | User story | `feature` | User story | |
| 116 | | BRD | Business enhancement | `enhancement` | Enhancement | |
| 117 | | ADR | Implementation task | `maintenance` | Task | |
| 118 | | ADR | Migration step | `breaking-change` | Task | |
| 119 | | RFC | Proposed capability | `feature` | Feature | |
| 120 | | Meeting notes | Action item | `maintenance` | Task | |
| 121 | | Security plan | Vulnerability remediation | `security` | Bug | |
| 122 | | Security plan | Hardening requirement | `security` | Enhancement | |
| 123 | | Backlog Brief | Experiment requirement | `experiment` | User story | |
| 124 | | Backlog Brief | Non-functional constraint | `experiment` | Task | |
| 125 | |
| 126 | When a document section contains acceptance criteria, include them in the candidate issue body as a checklist. |
| 127 | |
| 128 | #### Path C: Search-Based Discovery |
| 129 | |
| 130 | Use when: |
| 131 | |
| 132 | * User provides search terms directly ("find issues about authentication") |
| 133 | * No artifacts, documents, or assignment context apply |
| 134 | |
| 135 | Execution: |
| 136 | |
| 137 | 1. Call `mcp_github_get_me` to verify repository access. |
| 138 | 2. Build search queries from `searchTerms` scoped to `repo:{owner}/{repo}`. Apply `milestone:` qualifier when `milestone` is provided. |
| 139 | 3. Execute `mcp_github_search_issues` for each query and paginate results. |
| 140 | 4. Hydrate each result via `mcp_github_issue_read` with `method: 'get'`. When `includeSubIssues` is true, also fetch sub-issues. |
| 141 | 5. Present results grouped by state and labels. |
| 142 | 6. Create the planning folder at `.copilot-tracking/github-issues/discovery/<scope-name>/` and initialize *planning-log.md*. |
| 143 | 7. Log discovered issues in *planning-log.md* and deliver a conversational summary. |
| 144 | 8. Skip Phases 2-3; no additional planning files beyond *planning-log.md* are required for search-based discovery. |
| 145 | |
| 146 | ### Phase 2: Plan Issues |
| 147 | |
| 148 | Apply to artifact-driven discovery (Path B) only. |
| 149 | |
| 150 | #### Similarity-Based Actions |
| 151 | |
| 152 | | Category | Action | |
| 153 | |-----------|--------------------------------------------------------------------| |
| 154 | | Match | Link candidate to existing issue; plan an Update if fields diverge | |
| 155 | | Similar | Flag for user review with a comparison summary | |
| 156 | | Distinct | Plan as a new issue | |
| 157 | | Uncertain | Request user guidance before proceeding | |
| 158 | |
| 159 | #### Hierarchy Grouping |
| 160 | |
| 161 | Group related requirements into parent-child structures. When a requirement decomposes into more than 5 sub-requirements, create an epic-level tracking issue as the parent and link individual issues as sub-issues. |
| 162 | |
| 163 | Issue title conventions: |
| 164 | |
| 165 | * Feature and enhancement titles follow conventional commit format (for example, `feat(scope): description`). |
| 166 | * Assign labels per the Label Taxonomy Reference in *github-backlog-planning.instructions.md*. |
| 167 | * Assign milestones per the Milestone Discovery Protocol in *github-backlog-planning.instructions.md*. |
| 168 | |
| 169 | #### New Issue Construction |
| 170 | |
| 171 | * Populate acceptance criteria as markdown checkbox lists when extracted from documents. |
| 172 | * Use `{{TEMP-N}}` placeholders for issues not yet created, per the Temporary ID Mapping convention in #file:./github-backlog-planning.instructions.md. |
| 173 | * Include source references (document path and section) in issue body content only when the referenced path is committed to the repository. When referencing other planned issues, use `{{TEMP-N}}` placeholders (resolved to actual issue numbers during execution) or descriptive phrases. Apply the Content Sanitization Guards from #file:./github-backlog-planning.instructions.md before composing any GitHub-bound content. |
| 174 | |
| 175 | #### Existing Issue Handling |
| 176 | |
| 177 | * Match: Plan an Update action; merge new requirements while preserving existing content. |
| 178 | * Resolved or closed items satisfying the requirement: Set action to No Change and note the relationship for traceability. |
| 179 | |
| 180 | Record all planned operations in *issues-plan.md* per templates in *github-backlog-planning.instructions.md*. |
| 181 | |
| 182 | ### Phase 3: Assemble Handoff |
| 183 | |
| 184 | Apply to artifact-driven discovery (Path B) only. |
| 185 | |
| 186 | 1. Build *handoff.md* per the template in *github-backlog-planning.instructions.md*. Order: Create entries first, Update second, Link third, Close fourth, No Change last. |
| 187 | 2. Include checkboxes, summaries, relationships, and artifact references for each entry. |
| 188 | 3. Add a Planning Files section with project-relative paths to all generated files. |
| 189 | 4. Apply the Three-Tier Autonomy Model from *github-backlog-planning.instructions.md* to determine confirmation gates. When no tier is specified, default to Partial Autonomy. |
| 190 | 5. Verify consistency across *issue-analysis.md*, *issues-plan.md*, and *handoff.md*. |
| 191 | 6. Present the handoff for user review, highlighting items that trigger human review. |
| 192 | 7. Record the final state in *planning-log.md* with phase completion status. |
| 193 | |
| 194 | ## Human Review Triggers |
| 195 | |
| 196 | Pause and request user guidance when: |
| 197 | |
| 198 | * A requirement extracted from a document is ambiguous or contradicts another requirement. |
| 199 | * Multiple existing issues partially match a single candidate (two or more Similar results). |
| 200 | * A candidate implies a parent-child hierarchy, but the parent issue does not exist in the repository or candidate set. |
| 201 | * A candidate carries the `breaking-change` label, indicating potential release impact. |
| 202 | * The similarity assessment returns Uncertain for any pair. |
| 203 | * A planned operation changes an issue's milestone. |
| 204 | |
| 205 | Additional triggers are defined in the Human Review Triggers section of *github-backlog-planning.instructions.md*. |
| 206 | |
| 207 | ## Cross-References |
| 208 | |
| 209 | These sections in *github-backlog-planning.instructions.md* inform discovery operations: |
| 210 | |
| 211 | | Section | Used In | Purpose | |
| 212 | |---------------------------------|-----------------|--------------------------------------------------------| |
| 213 | | Search Protocol | Phase 1, Path B | Keyword group construction and query composition | |
| 214 | | Similarity Assessment Framework | Phase 1, Path B | Classifying candidate-to-existing issue pairs | |
| 215 | | Planning File Templates | Phases 1-3 | Structure for all output files | |
| 216 | | Content Sanitization Guards | Phase 2 | Strip local paths and planning IDs from GitHub content | |
| 217 | | Temporary ID Mapping | Phase 2 | `{{TEMP-N}}` placeholders for new issues | |
| 218 | | Three-Tier Autonomy Model | Phase 3 | Confirmation gates during handoff review | |
| 219 | | State Persistence Protocol | All phases | Context recovery after summarization | |
| 220 | | Issue Field Matrix | Phase 2 | Required and optional fields per operation type | |
| 221 | | Milestone Discovery Protocol | Phase 2 | Role-based milestone classification for assignment | |
| 222 | | Label Taxonomy Reference | Phase 2 | Label selection and title pattern mapping | |
| 223 | | Human Review Triggers | Phase 3 | Additional conditions for pausing execution | |
| 224 | |
| 225 | --- |
| 226 | |
| 227 | Brought to you by microsoft/hve-core |
| 228 | |