pull-next-backlog-ticket

name: pull-next-backlog-ticket description: >- Selects the next highest-priority open item from a GitHub Project backlog (Ready then Backlog, P0→P1→P2), claims it, and starts implementation. Use when the user asks to pull the next ticket, pick up backlog work, start the top priority issue, or work from a GitHub Project board (e.g. users/OWNER/projects/N).

Pull next backlog ticket

End-to-end: discover → rank → claim → implement. Works with any GitHub Project (classic fields: Status, Priority, Size, etc.).

Prerequisites

1. gh authenticated with project scope:

   gh auth status
   gh auth refresh -s project
   

2. Project identity — resolve before querying (see Configuration).
3. GitHub CLI for all GitHub ops (gh issue view, gh project item-edit, …). Use MCP only if gh fails.

Configuration

Step 0 — always: read .cursor/backlog-project.json at the root of any open workspace repo (griddungeon-game, griddungeon-design-docs). Grid Dungeon ships this file pre-filled for project 3. Do not search the repo or ask the user for the project URL when this file exists.

Resolve overrides in this order (first match wins after Step 0):

If no config file exists in any open workspace root, ask once for project URL or owner + number.

Typical overrides (optional JSON)

Workflow overview

Task Progress:
- [ ] 1. Resolve project + discover fields
- [ ] 2. Gather candidates (Ready → Backlog × priorities)
- [ ] 3. Rank and pick one issue
- [ ] 4. Claim on the board (+ optional gh issue assign)
- [ ] 5. Load full issue context and plan
- [ ] 6. Branch + implement
- [ ] 7. Handoff (PR / test plan) per repo rules

Step 1 — Resolve project and fields

gh project view <number> --owner <owner> --format json
gh project field-list <number> --owner <owner> --format json

From field-list, note IDs (not just names) for:

• Status (ProjectV2SingleSelectField) — map option names → single-select-option-id
• Priority — same
• Size — optional tie-break

If the board uses different labels (e.g. Todo instead of Backlog), update queries and backlog-project.json to match actual option names from field-list.

Step 2 — Gather candidates

Use Projects filter syntax with gh project item-list.

Base filter (always):

is:open is:issue -status:Done

Add exclusions from config, e.g. -label:blocked -label:wontfix.

Tier A — Ready column (highest intent to start)

For each priority in priorityOrder (or once without priority if the board has no Priority field):

gh project item-list <number> --owner <owner> --format json --limit <limit> \
  --query 'status:Ready priority:P0 is:open is:issue -status:Done'

Repeat for P1, P2, or omit priority: if the field does not exist.

Tier B — Backlog column

Same queries with status:Backlog (or configured backlogStatus).

Tier C — Resume (optional, ask user if ambiguous)

If the user said "continue" or has WIP:

gh project item-list <number> --owner <owner> --format json --limit 10 \
  --query 'status:"In progress" assignee:@me is:open is:issue'

If exactly one match, prefer it over pulling new work unless the user asked for a new ticket.

De-duplicate

Merge Tier A + B JSON items arrays; dedupe by content.url or id.

Step 3 — Rank and select one ticket

Apply in order until one winner remains:

1. Tier — Ready before Backlog.
2. Priority — P0 > P1 > P2 > unset (config order).
3. Repo relevance — If workspace has origin remotes, prefer issues where repository or content.repository matches an open folder’s repo (e.g. griddungeon-game vs griddungeon-design-docs). Use repoPrefer when set.
4. Feature scope — Prefer issues labeled required (or legacy mvp1) over optional when preferLabels is set in config.
5. Unblocked — Skip if body contains Depends on / Blocked by referencing open issues:

   gh issue view <owner>/<repo>#<n> --json state -q .state
   

   Skip when dependency state != CLOSED. (Heuristic; not all teams use this format.)
6. Size — Prefer smaller sizeOrder when still tied (quick wins).
7. Board order — If still tied, keep first item returned by item-list (approximates view order).

Announce the pick before coding:

## Next ticket
- **Issue:** <title> — <url>
- **Repo:** <owner/repo> #<number>
- **Project:** status <X>, priority <Y>, size <Z>
- **Why:** <one line: tier + priority + repo match + unblocked>

If no candidates: report empty tiers, suggest checking filters, adding Ready items, or lowering priority bar. Do not invent work.

Step 4 — Claim on the project board

1. Set Status → In progress (use discovered field + option IDs):

   gh project item-edit \
     --id <project-item-id> \
     --project-id <PVT_... from project view> \
     --field-id <status-field-id> \
     --single-select-option-id <in-progress-option-id>
   

2. Optionally assign on the issue:

   gh issue edit <url> --add-assignee @me
   

3. Optional comment:

   gh issue comment <url> --body "Picked up from project backlog — starting implementation."
   

Do not mark Done until the user confirms completion.

Step 5 — Load full issue context

gh issue view <url> --comments

Extract: Summary, Acceptance / checklist, Spec links, Related issues, Test plan, Out of scope.

Read linked design docs when the issue points to them (especially docs/ acceptance criteria).

Post a short implementation plan in chat (files to touch, repos, tests) before large edits.

Step 6 — Branch and implement

1. cd to the issue’s repo root (multi-root workspace: match repository from the item).
2. Branch from default branch:

   git fetch origin
   git checkout main && git pull   # or master
   git checkout -b issue-<number>-<short-slug>
   

3. Implement against Acceptance checkboxes; keep scope minimal (YAGNI).
4. Follow repo Cursor rules (format/review on commit, Unity test runner not CLI batch, etc.).

Step 7 — Handoff

Update project Status → In review when a PR is open (if that column exists).

Grid Dungeon defaults

Project board: Codename: GridDungeon. Defaults live in each repo’s .cursor/backlog-project.json (repoPrefer differs for game vs design-docs).

Failure modes

What not to do

• Do not run Unity batch tests while Editor may be open (see repo rules).
• Do not commit or push unless the user asks.
• Do not close issues without verification + test plan when required.
• Do not pull multiple tickets unless the user explicitly requests a batch.