GitHub Backlog Discovery

June 29, 2026 · View on GitHub

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.

Scope

Discovery path selection:

User-centric (Path A): User requests their issues, assigned work, or milestone progress without referencing artifacts
Artifact-driven (Path B): Documents, PRDs, or requirements provided for translation into issues
Search-based (Path C): User provides search terms directly without artifacts or assignment context

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).

Deliverables

File	Path A	Path B	Path C
planning-log.md	Yes	Yes	Yes
issue-analysis.md	No	Yes	No
issues-plan.md	No	Yes	No
handoff.md	No	Yes	No
Conversational summary	Yes	Yes	Yes

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.

Tooling

User-centric discovery (Path A):

mcp_github_get_me: Retrieve authenticated user details for assignee-based queries
mcp_github_search_issues: Search with assignee: qualifier scoped to repo:{owner}/{repo}
- Key params: query (required), owner, repo, perPage, page
mcp_github_issue_read: Hydrate results with method: 'get' for full details
- When includeSubIssues is true, also call with method: 'get_sub_issues'

Artifact-driven discovery (Path B):

read_file, grep_search: Read and parse source documents
mcp_github_get_me: Verify access to the target repository
mcp_github_search_issues: Execute keyword-group queries per the Search Protocol in github-backlog-planning.instructions.md
mcp_github_issue_read: Hydrate results and fetch sub-issues when enabled
mcp_github_list_issue_types: Retrieve valid issue types when the organization supports them

Search-based discovery (Path C):

mcp_github_search_issues: Execute user-provided terms scoped to repo:{owner}/{repo}
mcp_github_issue_read: Hydrate results with method: 'get' for full details

Workspace utilities: list_dir, read_file, semantic_search for artifact location and context gathering.

Required Phases

Phase 1: Discover Issues

Select the appropriate discovery path based on user intent and available inputs.

Path A: User-Centric Discovery

Use when:

User requests "show me my issues", "what's assigned to me", or similar
User asks about issues for a specific milestone or label scope
No artifacts or documents are referenced

Execution:

Call mcp_github_get_me to determine the authenticated user.
Build a search query with repo:{owner}/{repo} is:issue assignee:{username}. Apply milestone: and label: qualifiers when milestone or label context is provided.
Execute mcp_github_search_issues and paginate until all results are retrieved.
Hydrate each result via mcp_github_issue_read with method: 'get'. When includeSubIssues is true, also fetch sub-issues.
Present results grouped by state and labels.
Create the planning folder at .copilot-tracking/github-issues/discovery/<scope-name>/ and initialize planning-log.md.
Log discovered issues in planning-log.md and deliver a conversational summary.
Skip Phases 2-3; no additional planning files beyond planning-log.md are required for user-centric discovery.

Path B: Artifact-Driven Discovery

Use when:

Documents, PRDs, or requirements are provided via documents or conversation
User explicitly requests issue creation or updates from artifacts

Skip conditions:

No artifacts or documents are available; use Path A or Path C instead

Execution:

Create the planning folder at .copilot-tracking/github-issues/discovery/<scope-name>/.
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.
Read each document to completion and extract discrete requirements, acceptance criteria, and action items using the document parsing guidelines in this file.
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.
Build keyword groups from extracted requirements per the Search Protocol in github-backlog-planning.instructions.md.
Compose GitHub search queries scoped to repo:{owner}/{repo}. Apply milestone: qualifier when milestone is provided.
Execute mcp_github_search_issues for each keyword group and paginate results.
Hydrate each result via mcp_github_issue_read with method: 'get'. When includeSubIssues is true, also fetch sub-issues.
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.
De-duplicate results across keyword groups; retain the highest similarity category when the same issue appears in multiple searches.
Log all progress in planning-log.md with search queries, result counts, and similarity assessments.
Continue to Phase 2.

Document Parsing Guidelines

Map document types and content patterns to issue attributes.

Document Type	Content Pattern	Suggested Label	Issue Type
PRD	Feature requirement	`feature`	Feature
PRD	User story	`feature`	User story
BRD	Business enhancement	`enhancement`	Enhancement
ADR	Implementation task	`maintenance`	Task
ADR	Migration step	`breaking-change`	Task
RFC	Proposed capability	`feature`	Feature
Meeting notes	Action item	`maintenance`	Task
Security plan	Vulnerability remediation	`security`	Bug
Security plan	Hardening requirement	`security`	Enhancement
Backlog Brief	Experiment requirement	`experiment`	User story
Backlog Brief	Non-functional constraint	`experiment`	Task

When a document section contains acceptance criteria, include them in the candidate issue body as a checklist.

Path C: Search-Based Discovery

Use when:

User provides search terms directly ("find issues about authentication")
No artifacts, documents, or assignment context apply

Execution:

Call mcp_github_get_me to verify repository access.
Build search queries from searchTerms scoped to repo:{owner}/{repo}. Apply milestone: qualifier when milestone is provided.
Execute mcp_github_search_issues for each query and paginate results.
Hydrate each result via mcp_github_issue_read with method: 'get'. When includeSubIssues is true, also fetch sub-issues.
Present results grouped by state and labels.
Create the planning folder at .copilot-tracking/github-issues/discovery/<scope-name>/ and initialize planning-log.md.
Log discovered issues in planning-log.md and deliver a conversational summary.
Skip Phases 2-3; no additional planning files beyond planning-log.md are required for search-based discovery.

Phase 2: Plan Issues

Apply to artifact-driven discovery (Path B) only.

Similarity-Based Actions

Category	Action
Match	Link candidate to existing issue; plan an Update if fields diverge
Similar	Flag for user review with a comparison summary
Distinct	Plan as a new issue
Uncertain	Request user guidance before proceeding

Hierarchy Grouping

Group related requirements into parent-child structures using the Issue Type Strategy from github-backlog-planning.instructions.md:

Create a Feature issue when two or more related work items share a logical grouping or must be completed together.
Multi-level nesting (Feature → Feature → Task) is supported when sub-groups naturally exist within a larger capability.
Do not create a Feature wrapper for a single Task.
Feature issue bodies should list their children in a Children section for navigability.

Issue title conventions:

Feature and enhancement titles follow conventional commit format (for example, feat(scope): description).
Assign labels per the Label Taxonomy Reference in github-backlog-planning.instructions.md.
Assign milestones per the Milestone Discovery Protocol in github-backlog-planning.instructions.md.
Assign issue types per the Issue Type Strategy in github-backlog-planning.instructions.md when the organization supports them.

New Issue Construction

Structure issue bodies per the Issue Body Template in github-backlog-planning.instructions.md. Every new issue must include an Acceptance Criteria section with checkbox items.
Populate acceptance criteria from document requirements when available. When no explicit criteria exist in the source, derive them from the issue's scope and expected deliverables.
Use {{TEMP-N}} placeholders for issues not yet created, per the Temporary ID Mapping convention in #file:./github-backlog-planning.instructions.md.
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.
Include a Related section with parent references, dependencies, and domain context as applicable.

Existing Issue Handling

Match: Plan an Update action; merge new requirements while preserving existing content.
Resolved or closed items satisfying the requirement: Set action to No Change and note the relationship for traceability.

Record all planned operations in issues-plan.md per templates in github-backlog-planning.instructions.md.

Phase 3: Assemble Handoff

Apply to artifact-driven discovery (Path B) only.

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.
Include checkboxes, summaries, relationships, and artifact references for each entry.
Add a Planning Files section with project-relative paths to all generated files.
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.
Verify consistency across issue-analysis.md, issues-plan.md, and handoff.md.
Present the handoff for user review, highlighting items that trigger human review.
Record the final state in planning-log.md with phase completion status.

Human Review Triggers

Pause and request user guidance when:

A requirement extracted from a document is ambiguous or contradicts another requirement.
Multiple existing issues partially match a single candidate (two or more Similar results).
A candidate implies a parent-child hierarchy, but the parent issue does not exist in the repository or candidate set.
A candidate carries the breaking-change label, indicating potential release impact.
The similarity assessment returns Uncertain for any pair.
A planned operation changes an issue's milestone.

Additional triggers are defined in the Human Review Triggers section of github-backlog-planning.instructions.md.

Cross-References

These sections in github-backlog-planning.instructions.md inform discovery operations:

Section	Used In	Purpose
Search Protocol	Phase 1, Path B	Keyword group construction and query composition
Similarity Assessment Framework	Phase 1, Path B	Classifying candidate-to-existing issue pairs
Planning File Templates	Phases 1-3	Structure for all output files
Content Sanitization Guards	Phase 2	Strip local paths and planning IDs from GitHub content
Temporary ID Mapping	Phase 2	`{{TEMP-N}}` placeholders for new issues
Three-Tier Autonomy Model	Phase 3	Confirmation gates during handoff review
State Persistence Protocol	All phases	Context recovery after summarization
Issue Field Matrix	Phase 2	Required and optional fields per operation type
Milestone Discovery Protocol	Phase 2	Role-based milestone classification for assignment
Label Taxonomy Reference	Phase 2	Label selection and title pattern mapping
Human Review Triggers	Phase 3	Additional conditions for pausing execution
Issue Body Template	Phase 2	Standard body structure for new issues
Issue Type Strategy	Phase 2	Type classification and hierarchy rules