select-issue

Select Issue

Reads a GitHub Project (V2) and selects the next issue to work on by intersecting two project views:

1. A priority view (board or table grouped or sorted by priority), which ranks issues by priority.
2. A roadmap view (timeline grouped by an iteration or date field), which confirms the work is scheduled.

The selected issue is the highest-priority open issue that is also scheduled (planned) in the roadmap. This avoids working on high-priority-but-unplanned items and on planned-but-low-priority items.

Prerequisites

• gh CLI authenticated with read access to the project and its linked repositories
• The gh token must have the read:project scope (project fields and items require it). Refresh with gh auth refresh -s read:project if queries return INSUFFICIENT_SCOPES
• A GitHub Project (V2) that has a priority view and a roadmap view
• Project in owner/number format ($1), or omit to use GITHUB_PROJECT from .env
• Priority view name ($2), or omit to use PRIORITY_VIEW from .env, defaulting to Priority
• Roadmap view name ($3), or omit to use ROADMAP_VIEW from .env, defaulting to Roadmap

Resolution rules

1. Project: $1 overrides the GITHUB_PROJECT env var.
2. Priority view: $2 overrides the PRIORITY_VIEW env var, which overrides the default Priority.
3. Roadmap view: $3 overrides the ROADMAP_VIEW env var, which overrides the default Roadmap.

Workflow

Fetch project: fields, views, items (one GraphQL query)
         |
         v
Identify priority field (priority view group-by, else by name)
         |
         v
Identify roadmap scheduling field (iteration or date)
         |
         v
Build candidates: open, non-draft issues
         |
         v
For each candidate read: priority value + roadmap value
         |
         v
Filter to "planned": current or future roadmap slot
         |
         v
Sort: priority (field option order), then roadmap (soonest)
         |
         v
Select top candidate -> recommendation