Revamp find-reviewable-pr skill: priorities, defaults, and doc fixes

[PureWeen]

Note

Are you waiting for the changes in this PR to be merged?
It would be very helpful if you could test the resulting artifacts from this PR and let us know in a comment if this change resolves your issue. Thank you!

Description

Revamps the find-reviewable-pr skill with improved prioritization, better defaults, and documentation accuracy.

Changes

Script improvements (query-reviewable-prs.ps1):

• Default mode now shows only P/0 + milestoned PRs (most actionable), filtering out changes-requested
• Added Approved (not merged) and Ready To Review (project board) categories
• Added Agent Reviewed category with AI summary highlights
• Added Assignees column to output
• Removed single-PR review section (will be a separate skill)
• Limit increased to 20 per category

Documentation fixes (SKILL.md):

• Fixed priority order: Milestoned (Aloha System.Maui! #4) before Agent Reviewed (Update README.md #5) to match script
• Added default as valid -Category value with description
• Fixed -Limit default from 10 to 20 to match script
• Updated presentation order in Step 3 to match script

Review consensus

These doc fixes were identified by a multi-model review (7 AI models agreed on priority order, 5 agreed on category/limit defaults).

[Copilot]

Pull request overview

Updates the find-reviewable-pr skill to better surface the most actionable PRs first by adjusting defaults, adding new prioritization categories (approved, project-board “Ready To Review”, agent-reviewed), and aligning user-facing documentation with the script’s intended behavior.

Changes:

• Changed the default category behavior and increased per-category limits.
• Added new PR categories (Approved, Ready To Review via project board, Agent Reviewed) and expanded output fields (e.g., assignees + agent summary highlights).
• Updated SKILL.md to document the new categories/parameters and revised ordering.

Reviewed changes

Copilot reviewed 2 out of 2 changed files in this pull request and generated 8 comments.

File	Description
.github/skills/find-reviewable-pr/scripts/query-reviewable-prs.ps1	Adds new query paths/categories, project-board integration, agent-summary extraction, output refactor, and new defaults.
.github/skills/find-reviewable-pr/SKILL.md	Updates skill documentation to describe new categories, defaults, and output expectations.

[Copilot]

The Quick Start section still frames the default script invocation as returning "all reviewable PRs" / "top from each category", but the script now defaults to -Category default (P/0 + milestoned only). Please update the Quick Start prose/example to reflect the new default behavior, and add/keep an explicit -Category all example for the previous behavior.

[Copilot]

The comment-based help block at the top (the .DESCRIPTION prioritization list) still describes the old ordering/categories (milestoned first, no approved/ready-to-review/agent-reviewed). Since the script behavior has changed significantly, please update that list so Get-Help reflects the current prioritization and default behavior.

[Copilot]

-Limit default was changed to 20, but the comment-based help text above still says the default is 10 (".PARAMETER Limit ... (default: 10)"). Please update the help text to match the actual default so Get-Help output is accurate.

[Copilot]

The GraphQL query string is flattened with -replace "n", " ", but on Windows the here-string will typically contain CRLF, leaving stray \rcharacters in the command. This can causegh api graphqlto fail intermittently. Consider replacing both CRLF/LF (e.g.,-replace "r?n", " "or-replace "r", "" after handling \n).

Suggested change

	$result = Invoke-GitHubWithRetry -Command "gh api graphql -f query='$($graphqlQuery -replace "`n", " " -replace "'", "'\''")'" -Description "fetch project board items"
	$result = Invoke-GitHubWithRetry -Command "gh api graphql -f query='$($graphqlQuery -replace "`r?`n", " " -replace "'", "'\''")'" -Description "fetch project board items"

[Copilot]

The project board query requests only items(first: 100). If the project contains more than 100 items, PRs beyond the first page will never be considered "Ready To Review". Consider adding pagination (pageInfo/endCursor) to fetch all pages (or at least until no more matching PRs are found).

[Copilot]

Get-AgentSummaryComment calls the issue comments REST endpoint without pagination. GitHub defaults to the first page (typically 30 comments), so the AI Summary marker may be missed on PRs with longer discussions. Consider requesting per_page=100 and paginating (or using GraphQL) to reliably find the comment.

Suggested change

	$result = gh api "repos/dotnet/maui/issues/$PRNumber/comments" --jq '.[] | select(.body | contains("<!-- AI Summary -->")) | .body' 2>&1
	$result = gh api "repos/dotnet/maui/issues/$PRNumber/comments" -F per_page=100 --paginate --jq '.[] | select(.body | contains("<!-- AI Summary -->")) | .body' 2>&1

[Copilot]

Agent summaries are fetched for all PRs with agent labels immediately after processing, even when -Category default (or other categories) won't display Agent Reviewed results. This can add a lot of extra gh api calls and slow down the default path. Consider fetching summaries only when the output will include agent-reviewed PRs (e.g., -Category agent-reviewed/all, or when OutputFormat is json and you include the summary fields).

Suggested change

	# Fetch agent summaries for agent-reviewed PRs
	$agentReviewedPRs = $processedPRs | Where-Object { $_.HasAgentReview }
	if ($agentReviewedPRs.Count -gt 0) {
	Write-Host ""
	Write-Host "Fetching agent review summaries..." -ForegroundColor Cyan
	foreach ($pr in $agentReviewedPRs) {
	Write-Host " PR #$($pr.Number)..." -ForegroundColor Gray -NoNewline
	$commentBody = Get-AgentSummaryComment -PRNumber $pr.Number
	if ($commentBody) {
	$pr.AgentSummary = Get-AgentSummaryHighlights -CommentBody $commentBody
	Write-Host " ✓" -ForegroundColor Green
	} else {
	Write-Host " (no AI Summary comment found)" -ForegroundColor Yellow
	# Decide whether we actually need to fetch agent summaries for this invocation
	$shouldFetchAgentSummaries = $false
	# Fetch summaries when agent-reviewed PRs will be shown explicitly
	if ($Category -eq 'agent-reviewed' -or $Category -eq 'all') {
	$shouldFetchAgentSummaries = $true
	}
	# Or when JSON output is requested and agent-summary-related fields are included
	elseif ($OutputFormat -eq 'json' -and $Fields) {
	$fieldsText = ($Fields -join ',')
	if ($fieldsText -match 'AgentSummary' -or $fieldsText -match 'HasAgentReview') {
	$shouldFetchAgentSummaries = $true
	}
	}
	# Fetch agent summaries for agent-reviewed PRs only when needed
	if ($shouldFetchAgentSummaries) {
	$agentReviewedPRs = $processedPRs | Where-Object { $_.HasAgentReview }
	if ($agentReviewedPRs.Count -gt 0) {
	Write-Host ""
	Write-Host "Fetching agent review summaries..." -ForegroundColor Cyan
	foreach ($pr in $agentReviewedPRs) {
	Write-Host " PR #$($pr.Number)..." -ForegroundColor Gray -NoNewline
	$commentBody = Get-AgentSummaryComment -PRNumber $pr.Number
	if ($commentBody) {
	$pr.AgentSummary = Get-AgentSummaryHighlights -CommentBody $commentBody
	Write-Host " ✓" -ForegroundColor Green
	} else {
	Write-Host " (no AI Summary comment found)" -ForegroundColor Yellow
	}

[Copilot]

-Category default is now the script default, but the category filter switch doesn't handle it. As a result, -OutputFormat table (and the returned $processedPRs for non-review outputs) will include all processed PRs instead of only P/0 + milestoned (and excluding changes-requested) as documented. Add an explicit "default" case that sets $processedPRs to the intended filtered set (and consider de-duping between priority/milestoned).

Suggested change

	"docs-maui" { $processedPRs = @() } # Will be handled separately
	"docs-maui" { $processedPRs = @() } # Will be handled separately
	"default" {
	# Default: P/0 + milestoned, excluding changes-requested, with de-duplication
	$defaultPRs = @()
	if ($priorityPRs) { $defaultPRs += $priorityPRs }
	if ($milestonedPRs) { $defaultPRs += $milestonedPRs }
	$processedPRs = $defaultPRs |
	Where-Object { $_.ReviewDecision -ne "CHANGES_REQUESTED" } |
	Sort-Object Number -Unique
	}