Ghs Backlog Next

Backlog Next

Quickly find and recommend the single highest-impact backlog item to work on next. Returns one recommendation with the command to apply it.

No sub-agents — this is a lightweight, read-only skill.

References:

• ../shared/references/gh-cli-patterns.md
• ../shared/references/output-conventions.md
• ../shared/references/ui-brand.md
• ../shared/references/argument-parsing.md
• ../shared/references/projects-format.md
• ../shared/references/scoring-logic.md
• ../shared/references/config.md

Purpose: Read-only recommendation engine that selects the single highest-impact project item using the priority algorithm.

Roles:

1. Recommender (you) — queries GitHub Project items, applies priority algorithm, displays the top recommendation

No sub-agents — this is a lightweight, read-only skill.

Shared References

| Reference | Path | Purpose | |-----------|------|---------| | Scoring Logic | ../shared/references/scoring-logic.md | Tier weights, priority algorithm, score formula | | Projects Format | ../shared/references/projects-format.md | Project naming, item schema, jq scoring pipelines, state issue lookup | | Output Conventions | ../shared/references/output-conventions.md | Status indicators, table patterns, progress bars | | State Persistence | ../shared/references/state-persistence.md | State issue format, blocker/decision/session data for filtering | | Config | ../shared/references/config.md | Scoring constants, display thresholds | | gh CLI Patterns | ../shared/references/gh-cli-patterns.md | Project Operations section — auth check, project discovery, item queries |

Anti-Patterns

| Do NOT | Do Instead | Why | |--------|-----------|-----| | Recommend an already-fixed (Done) item | Always check current Status from the project item before recommending | Wastes the user's time on completed work | | Recommend without verifying item still exists | Confirm the project item is present and status is Todo | Item may have been deleted or moved to Done after a fix | | Show multiple recommendations as a list | Return exactly one item; show a single runner-up line only if multiple repos exist | Defeats the purpose of "next ONE item" — causes decision paralysis | | Guess the score instead of calculating | Always use the jq pipeline from projects-format.md for accurate scores | Produces wrong priority ordering | | Recommend WARN items as actionable | Skip WARN items (they are never in the project); only mention them if nothing else remains | WARN means permission-blocked; user cannot fix it | | Recommend items with ACTIVE blockers in the state issue | Read the state issue and exclude blocked/recently-failed/skipped items | Wastes time on items that are known to be unresolvable right now | | Ignore the state issue when it exists | Always check the state issue before recommending — it has blockers, failures, and skip decisions | Missing context leads to recommending items that will fail again |

Input

No input required. Discovers all [GHS] projects for the owner automatically.

Optional: the user may specify a repo to limit the search — "next for phmatray/Formidable".

| Trigger | Example | Behavior | |---------|---------|----------| | General next | "what should I work on next?" | Scan all [GHS] projects, pick the single best item | | Repo-scoped next | "next for phmatray/Formidable" | Limit search to [GHS] phmatray/Formidable project only | | After a fix | "next" | Previous fix is now Done, pick the next best item |

Pre-flight

Verify project scope before any project API call:

gh auth status 2>&1 | grep -q "project" || echo "[FAIL] Run: gh auth refresh -s project"

• Read all projects via gh project item-list for recommendation data

Process

Phase 1 — Discover Failing Items

Discover all [GHS] projects for the owner (or the specified project):

gh project list --owner {owner} --format json \
  --jq '.projects[] | select(.title | startswith("[GHS]"))'

For each project, query all items and filter for health check items in the Todo column:

ITEMS=$(gh project item-list $PROJECT_NUM --owner {owner} --format json --limit 500)

# Health check items that need fixing
FAIL_ITEMS=$(echo "$ITEMS" | jq '[.items[] | select(.source == "Health Check" and .status == "Todo")]')

For each failing item, extract:

| Field | Source | |-------|--------| | Repository | From project title (strip [GHS] prefix) | | Check name | From item title (strip [Health] prefix) | | Tier | From item tier field (1 — Required, 2 — Recommended, 3 — Nice to Have) | | Points | From item points field (4, 2, or 1) | | Slug | From item slug field | | Category | From item category field | | Status | Todo only; skip Done and In Progress |

Also look for GitHub Issue items in the Todo column — issues are secondary to health items:

OPEN_ISSUES=$(echo "$ITEMS" | jq '[.items[] | select(.source == "GitHub Issue" and .status == "Todo")]')

Phase 1.5 — Filter Using State Issue

For each repo, look up the state issue if it exists:

gh issue list --repo {owner}/{repo} --label "ghs:state" --state open \
  --json number,title,body --limit 1

Use the state issue body to exclude items from the candidate pool:

| State Issue Data | Filter Rule | |-----------------|-------------| | Active blockers | Exclude items listed in the Affected Items column of ACTIVE blockers | | Last session failures | Exclude items that FAILED in the most recent session (unless user says "retry") | | Decisions with skip | Exclude items the user explicitly decided to skip |

> Rule: State issue filtering happens before the priority algorithm. Only unblocked, non-failed, non-skipped items enter the ranking. > > Trigger: State issue exists for the repo being evaluated > > Example: State issue has branch-protection as affected by an ACTIVE blocker "No admin access" — skip [Health] Branch Protection project item even though it is Tier 1 with 4 points.

If no state issue exists for the repo, skip this phase — all Todo health items are candidates.

Phase 2 — Select the Highest-Impact Item

Apply the priority algorithm (see scoring-logic.md for canonical definition):

| Priority | Rule | |----------|------| | 1 | Lowest health score percentage repo first | | 2 | Health items over issues (structural foundation) | | 3 | Lowest tier number (Tier 1 before Tier 2 before Tier 3) | | 4 | Highest point value within same tier | | 5 | Oldest issue (by creation date) for issue items | | 6 | Alphabetical (final tiebreaker) |

Calculate per-repo scores using the jq pipeline from projects-format.md:

ITEMS=$(gh project item-list $PROJECT_NUM --owner {owner} --format json --limit 500)
EARNED=$(echo "$ITEMS" | jq '[.items[] | select(.source == "Health Check" and .status == "Done") | .points] | add // 0')
POSSIBLE=$(echo "$ITEMS" | jq '[.items[] | select(.source == "Health Check" and (.status == "Todo" or .status == "Done")) | .points] | add // 0')
SCORE=$(echo "scale=0; $EARNED * 100 / $POSSIBLE" | bc)

Alternatively, read the cached score from the [GHS Score] item for efficiency:

SCORE_BODY=$(echo "$ITEMS" | jq -r '.items[] | select(.title == "[GHS Score]") | .body' | jq '.score')

Tie between repos with same score: pick the one with the most failing items.

Phase 3 — Display Recommendation

Standard recommendation

## Next: {Check Name}

Repository:  {owner}/{repo} ({score}% health)
Source:      Health Check — Tier {N} ({Required|Recommended|Nice to Have})
Points:      {points}
Category:    {A (API-only) | B (file changes) | CI}

Why this item: {one sentence — e.g., "Lowest-scoring repo, highest-tier failing check."}
{If items were filtered by state issue:}
Skipped: {N} items excluded (blocked: {b}, recent failures: {f}, user-skipped: {s})

To apply:
  /ghs-backlog-fix {owner}/{repo} --item {slug}

{If item has a linked GitHub issue:}
GitHub Issue: https://github.com/{owner}/{repo}/issues/{number}

If there are multiple repos, also show the runner-up (one line only):

Runner-up: {Check Name} for {owner}/{repo} ({score}% health, Tier {N}, {points} pts)

All caught up

If all health items are Done and all issues are Done or In Progress:

## All caught up!

All health checks are passing and all issues have been addressed.
To re-scan for changes: /ghs-repo-scan {owner}/{repo}

Good and Bad Examples

Good: Clear single recommendation

## Next: LICENSE

Repository:  phmatray/Formidable (32% health)
Source:      Health Check — Tier 1 (Required)
Points:      4
Category:    B (file changes)

Why this item: Lowest-scoring repo, highest-tier failing check worth 4 points.

To apply:
  /ghs-backlog-fix phmatray/Formidable --item license

Bad: Multiple recommendations dumped as a list

Here are the top 5 items you should work on:
1. LICENSE for phmatray/Formidable
2. README for phmatray/Formidable
3. .editorconfig for phmatray/Formidable
4. SECURITY.md for phmatray/Formidable
5. Branch protection for phmatray/Formidable

Why it is bad: defeats the purpose of "next ONE item" and creates decision paralysis. Use ghs-backlog-board for full lists.

Bad: Recommending a Done item

## Next: README.md

Repository:  phmatray/Formidable (75% health)
Source:      Health Check — Tier 1 (Required)
Points:      4

To apply:
  /ghs-backlog-fix phmatray/Formidable --item readme

Why it is bad: README project item has status Done. Always verify the item's current Status field before recommending.

Edge Cases

| Situation | Action | |-----------|--------| | No GitHub Projects found | Tell user no scans have been run; suggest /ghs-repo-scan {owner}/{repo} | | All items Done | Display the "All caught up!" message | | Only WARN items left | Explain remaining items are permission-blocked (not in project); suggest checking access | | Multiple repos tied on score | Pick the one with the most failing items | | Stale data ([GHS Score] updated > 30 days ago) | Note it and suggest re-scanning: /ghs-repo-scan {owner}/{repo} | | All Todo items blocked by state issue | Show "All remaining items are blocked" with blocker summary; suggest resolving blockers | | User says "retry" after blocked recommendation | Ignore state issue filters for that item and recommend it anyway | | No state issue exists | Normal flow — all Todo items are candidates (no filtering) |

Routing

| After This Skill | Suggest | |-----------------|---------| | User wants to apply the fix | /ghs-backlog-fix {owner}/{repo} --item {slug} | | Everything is done | /ghs-repo-scan {owner}/{repo} to re-scan for changes | | User wants a full overview | /ghs-backlog-board for the multi-repo dashboard |

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: Atypical-Consulting
• Source: Atypical-Consulting/GitHubSkills
• License: MIT
• Homepage: https://atypical-consulting.github.io/GitHubSkills/

Install and usage instructions live in the source repository linked above.