|
| 1 | +--- |
| 2 | +description: Identify what to focus on next based on PRs, issues, and milestones |
| 3 | +argument-hint: [--contributing path] |
| 4 | +--- |
| 5 | + |
| 6 | +## Name |
| 7 | +github:what-next |
| 8 | + |
| 9 | +## Synopsis |
| 10 | +``` |
| 11 | +/github:what-next [--contributing path] |
| 12 | +``` |
| 13 | + |
| 14 | +## Description |
| 15 | +The `github:what-next` command helps developers identify what to focus on next by analyzing open PRs, assigned work, and milestone issues. It presents a prioritized list of actionable items based on common open-source contribution workflows. |
| 16 | + |
| 17 | +This command is particularly useful for: |
| 18 | +- Starting your work day with a clear focus |
| 19 | +- Identifying PRs that need your review |
| 20 | +- Tracking the status of your own PRs |
| 21 | +- Finding priority issues to work on next |
| 22 | +- Understanding your current workload at a glance |
| 23 | + |
| 24 | +The command automatically: |
| 25 | +- Identifies PRs where your review is needed |
| 26 | +- Shows your open PRs and their review status |
| 27 | +- Finds priority issues from the next milestone |
| 28 | +- Respects contribution guidelines if present |
| 29 | + |
| 30 | +## Prerequisites |
| 31 | + |
| 32 | +1. **GitHub CLI (`gh`)** must be installed and authenticated |
| 33 | + - Check: `gh auth status` |
| 34 | + - Install: https://cli.github.com/ |
| 35 | + |
| 36 | +2. **Repository context**: Must be run from within a Git repository that has a GitHub remote |
| 37 | + |
| 38 | +## Implementation |
| 39 | + |
| 40 | +Execute the following steps to gather information and present suggestions: |
| 41 | + |
| 42 | +### Step 1: Get GitHub Username |
| 43 | +```bash |
| 44 | +gh api user --jq '.login' |
| 45 | +``` |
| 46 | +Store this as `GITHUB_USER` for filtering throughout. |
| 47 | + |
| 48 | +### Step 2: Read Contribution Guidelines (Optional) |
| 49 | +If `--contributing` path is provided, or if `CONTRIBUTING.md` exists in the repository root: |
| 50 | +- Read the file to understand project-specific review and priority conventions |
| 51 | +- Look for guidance on: |
| 52 | + - Required number of reviewers |
| 53 | + - Priority label conventions |
| 54 | + - Milestone-based workflows |
| 55 | + - Any special review request processes |
| 56 | + |
| 57 | +If no contributing file is found, use sensible defaults. |
| 58 | + |
| 59 | +### Step 3: Fetch Open PRs |
| 60 | +```bash |
| 61 | +gh pr list --state open --json number,title,author,isDraft,reviewRequests,reviews,assignees,updatedAt,url |
| 62 | +``` |
| 63 | + |
| 64 | +Process the PR data into categories: |
| 65 | + |
| 66 | +**A. PRs Needing Your Review** (highest priority): |
| 67 | +- Exclude drafts (unless you're an assignee with recent comments) |
| 68 | +- Exclude PRs authored by you |
| 69 | +- Exclude PRs that are "sufficiently reviewed" (see heuristics below) |
| 70 | +- Prioritize PRs where you are explicitly in `reviewRequests` |
| 71 | + |
| 72 | +**B. Your Assigned PRs with Activity**: |
| 73 | +- PRs where you are an assignee (including drafts) |
| 74 | +- Check for recent comments that may need response: |
| 75 | + ```bash |
| 76 | + gh pr view <number> --json comments --jq '.comments[-1]' |
| 77 | + ``` |
| 78 | + |
| 79 | +**C. Your Open PRs (non-draft)**: |
| 80 | +- PRs authored by you that are not drafts |
| 81 | +- Categorize by review status: |
| 82 | + - Has APPROVED and no CHANGES_REQUESTED = ready to merge |
| 83 | + - Has CHANGES_REQUESTED = needs your attention |
| 84 | + - No reviews yet = waiting for review |
| 85 | + |
| 86 | +**D. Your Drafts**: |
| 87 | +- Draft PRs authored by you |
| 88 | +- Note how recently they were updated |
| 89 | + |
| 90 | +### Step 4: Find Milestone Issues |
| 91 | +Get the next milestone with a due date: |
| 92 | +```bash |
| 93 | +gh api repos/:owner/:repo/milestones --jq '[.[] | select(.state == "open") | select(.due_on)] | sort_by(.due_on) | .[0] | {number, title, due_on}' |
| 94 | +``` |
| 95 | + |
| 96 | +If a milestone exists, fetch its issues: |
| 97 | +```bash |
| 98 | +gh issue list --milestone "<milestone_title>" --state open --json number,title,labels,assignees,url |
| 99 | +``` |
| 100 | + |
| 101 | +Sort issues by priority labels (common conventions): |
| 102 | +1. `priority/critical` or `critical` - highest |
| 103 | +2. `priority/high` or `high-priority` |
| 104 | +3. `priority/normal` or no priority label |
| 105 | +4. `priority/low` or `low-priority` |
| 106 | + |
| 107 | +Also recognize: |
| 108 | +- `good first issue` - suitable for newcomers |
| 109 | +- `help wanted` - explicitly seeking contributors |
| 110 | + |
| 111 | +Select up to 3 issues, preferring: |
| 112 | +1. Unassigned issues |
| 113 | +2. Issues assigned to the current user |
| 114 | +3. Issues with `help wanted` label |
| 115 | + |
| 116 | +### Step 5: Format Output |
| 117 | + |
| 118 | +Present findings as a prioritized action list: |
| 119 | + |
| 120 | +```markdown |
| 121 | +## What to Focus on Next |
| 122 | + |
| 123 | +### PRs Needing Your Review |
| 124 | +1. [PR #123](url) - "Title" by @author |
| 125 | + - You were requested as reviewer |
| 126 | + - Updated 2 hours ago |
| 127 | + |
| 128 | +### Your Assigned PRs with Activity |
| 129 | +1. [PR #456](url) - "Title" (draft) |
| 130 | + - @someone commented 3 hours ago - may need response |
| 131 | + |
| 132 | +### Your Open PRs |
| 133 | +1. [PR #789](url) - "Title" |
| 134 | + - Status: Approved, ready to merge |
| 135 | +2. [PR #790](url) - "Title" |
| 136 | + - Status: Changes requested by @reviewer |
| 137 | + |
| 138 | +### Your Drafts |
| 139 | +1. [PR #791](url) - "Title" |
| 140 | + - Last updated 3 days ago |
| 141 | + |
| 142 | +### Priority Issues for [Milestone Name] (due YYYY-MM-DD) |
| 143 | +1. [#100](url) - "Issue title" `priority/high` |
| 144 | + - Unassigned |
| 145 | +2. [#101](url) - "Another issue" `help wanted` |
| 146 | + - Assigned to you |
| 147 | +3. [#102](url) - "Third issue" |
| 148 | + - Unassigned |
| 149 | + |
| 150 | +--- |
| 151 | +*PRs take precedence over new work. Review others' PRs first, then address feedback on yours, then pick up new issues.* |
| 152 | +``` |
| 153 | + |
| 154 | +If any section is empty, note it (e.g., "No PRs currently need your review"). |
| 155 | + |
| 156 | +### Sufficient Review Heuristics |
| 157 | + |
| 158 | +A PR is considered "sufficiently reviewed" (exclude from review list) if: |
| 159 | +- Has 1+ APPROVED review AND no CHANGES_REQUESTED |
| 160 | +- Has CHANGES_REQUESTED (needs author attention, not more reviews) |
| 161 | +- Has 2+ reviews submitted in the last 24 hours (active discussion) |
| 162 | +- All explicitly requested reviewers have submitted reviews |
| 163 | + |
| 164 | +### Error Handling |
| 165 | + |
| 166 | +- **Not in a git repo**: Display error and suggest running from a repository |
| 167 | +- **gh not authenticated**: Display error with `gh auth login` instructions |
| 168 | +- **No GitHub remote**: Display error explaining GitHub remote is required |
| 169 | +- **No milestones**: Skip the milestone section, note "No open milestones with due dates" |
| 170 | +- **API rate limits**: Display warning and suggest waiting |
| 171 | + |
| 172 | +## Return Value |
| 173 | + |
| 174 | +- **Console Output**: Formatted markdown summary of prioritized work items |
| 175 | +- **Sections included**: |
| 176 | + - PRs needing review (from others) |
| 177 | + - Your assigned PRs with activity |
| 178 | + - Your open PRs with status |
| 179 | + - Your draft PRs |
| 180 | + - Priority issues from next milestone |
| 181 | + |
| 182 | +## Examples |
| 183 | + |
| 184 | +1. **Basic usage**: |
| 185 | + ``` |
| 186 | + /github:what-next |
| 187 | + ``` |
| 188 | + Output: Prioritized list of PRs and issues based on default heuristics |
| 189 | + |
| 190 | +2. **With custom contributing file**: |
| 191 | + ``` |
| 192 | + /github:what-next --contributing docs/CONTRIBUTING.md |
| 193 | + ``` |
| 194 | + Output: Same as above, but uses project-specific conventions from the specified file |
| 195 | + |
| 196 | +3. **In a repo with no open PRs or milestones**: |
| 197 | + ``` |
| 198 | + /github:what-next |
| 199 | + ``` |
| 200 | + Output: |
| 201 | + ```markdown |
| 202 | + ## What to Focus on Next |
| 203 | + |
| 204 | + ### PRs Needing Your Review |
| 205 | + No PRs currently need your review. |
| 206 | + |
| 207 | + ### Your Open PRs |
| 208 | + You have no open PRs. |
| 209 | + |
| 210 | + ### Priority Issues |
| 211 | + No open milestones with due dates found. |
| 212 | + |
| 213 | + --- |
| 214 | + *Consider checking the issue tracker for unassigned issues or starting new work.* |
| 215 | + ``` |
| 216 | + |
| 217 | +## Arguments |
| 218 | + |
| 219 | +- `--contributing` (optional): Path to a contributing guidelines file |
| 220 | + - Default: Looks for `CONTRIBUTING.md` in repository root |
| 221 | + - If provided, reads project-specific conventions for review requirements and priority labels |
| 222 | + - Example: `--contributing docs/CONTRIBUTING.md` |
| 223 | + |
| 224 | +## See Also |
| 225 | +- `git:summary` - Quick overview of repository state |
| 226 | +- `git:suggest-reviewers` - Find appropriate reviewers for your PR |
0 commit comments