Powertoys Pr Review

PowerToys PR Review

Review a microsoft/PowerToys pull request the way a maintainer would, given a PR number N. The review has two halves that run in parallel:

1. Context & process review (Phase 0) — the checks Copilot code review can never do: is the CLA signed, is there a demo for a user-visible change, did the author validate it, is it original work, a duplicate, in-scope, CI-green, and template-complete? Aimed at community-contributor PRs and often the deciding factor. See references/phase0-context-review.md.
2. Code review (Steps 0–10) — mirror the PR to the reviewer's personal fork, iterate GitHub Copilot review to convergence, fix valid issues, build locally, and draft suggested-fix comments.

Never post anything to the original PR without explicit user approval (Step 10).

When to Use This Skill

• "Review PR N" / "review this PowerToys PR" / "continue the review for PR N"
• Self-check your own PowerToys PR before a maintainer sees it
• Draft inline code suggestions (click-to-commit) with severity for a PR
• Decide the process disposition (proceed / ask / align / recommend-close) for a community PR

Review Modes

Prerequisites (verify on first run)

Run scripts/Test-Prerequisites.ps1 to check all four at once. Detail and setup guidance: references/prerequisites.md.

If a prerequisite is missing, guide the user through setup (references/prerequisites.md) before proceeding. Do not infer that prerequisite 3 is missing solely from an empty requested_reviewers response; check for a review submitted after the request. Prerequisite 3 must be enabled by the user in the fork's settings; for 4, offer to install the tools via winget.

Critical Rules

1. Never post comments, suggestions, reviews, approvals, labels, or close actions on the original PR until the user gives explicit written approval in Step 10. This includes gh pr review, gh pr close, gh pr edit --add-label, or any command targeting microsoft/PowerToys. Violating this is a critical failure.
2. Never approve the original PR — even after user approval. Draft suggestions/requests/dispositions only; the human makes the final call.
3. Run Phase 0 in parallel with the code review for community PRs. A perfectly-coded PR can still need a demo, CLA, validation, or a close. Context findings are first-class output.
4. Respect author type, and do not over-gate. Skip Phase 0 process nags for members/collaborators/bots; hold community contributors to the gates but stay welcoming. Most well-formed PRs trip no gate — do not invent friction.
5. Never use #<number> format in any fork PR title or description — it notifies the referenced upstream thread. Use plain numbers.
6. Skip fork-mirroring in self-check mode (author is the fork owner): review and build in the author's own worktree; Steps 1–2c do not apply.
7. All code work happens on the fork and locally until final approval.
8. The local worktree must build successfully before a deep code review is marked complete.
9. Always sync the fork's main before creating or updating the fork PR to prevent diff bloat from a stale base (Step 2c).
10. Resume, do not restart (Step 0). Before mirroring, check for a prior interrupted run on PR N and pick up from the matching step instead of re-mirroring. Re-mirroring clobbers prior commits and review replies.
11. The fork Copilot loop (Steps 4–8) is not optional and is independent of the posting decision. "Just show me" / "do not post" changes only Step 10. You must still drive the fork loop to convergence: fix valid issues, commit, push, reply-and-resolve every Copilot thread, and re-request review until a freshly-requested review returns zero new comments and there are zero unresolved Copilot threads. Final suggestions come from the converged net diff, never raw round-1 output.
12. For 2+ independent PRs, review them in parallel unless the user explicitly requests sequential execution. Fan out one background worker per PR (cap 3–5 concurrent), with an isolated branch/worktree and independent convergence loop. If sub-agents are unavailable, pipeline all PRs in one agent so their review requests and waits remain concurrently in flight. Sync the base once, serialize local builds, and keep the orchestrator as the single writer of dashboard data. Never leave any PR stranded at round 1. See batch-parallel.md.
13. Never mention a fork repository, fork PR, worktree, internal review loop, or private validation provenance in comments posted to the original PR. Store that evidence only under internalEvidence; public payloads must be self-contained.
14. Never post prose summaries as inline code suggestions. An inline item must contain one non-empty, apply-ready suggestion block targeting an exact current RIGHT-side diff range. Split localized fixes out of broader multi-file findings instead of collapsing every concrete change into companion prose. Use a companion item only for the architectural, coordination, or out-of-diff remainder, and explicitly label companion-only reviews as general notes with no inline suggestions. Omit obsolete findings.
15. Never publish with ad-hoc gh commands. Validate schema-version-2 data with Test-ReviewData.ps1, then publish approved decisions with Publish-ApprovedReview.ps1. The publisher stages a pending review, reads it back, and submits only after exact verification.
16. Score confidence per finding, but never expose it upstream. Every drafted public item carries a 50–100 confidence score and evidence-based rationale as metadata. Scores below 50 stay internal. Pulse may show the score to maintainers; author-facing review bodies must contain severity and reasoning only.
17. Fork pushes are required review work, not upstream publication. Workers may create/update branches and PRs in the configured personal fork, push review fixes, and resolve fork review threads. A coordinator instruction not to commit or push dashboard data must never be interpreted as prohibiting fork-side pushes. Only writes to microsoft/PowerToys remain approval-gated.
18. Resolve the writable fork from configuration and clone remotes, not only the active login. Get-ForkConfig.ps1 prefers POWERTOYS_FORK_REPO, then a non-Microsoft PowerToys remote in the local clone, and switches to the authenticated fork-owner account when the current account has read-only access. Do not substitute <active-login>/PowerToys when the durable review branches live in another configured account.
19. Use the dashboard terminal-stage contract. Emit a clean current-head review with zero proposed comments as stage: review_ready, never concluded, complete, or another synonym. A review with findings must instead include a current-head post_review or request_changes action. When automation cannot proceed, emit stage: review_blocked only for a current-head terminal blocker and include blockers[] entries with non-empty detail and exact remediation; do not leave it as review_in_progress.

Phase 0: Context & Process Review

The half Copilot code review cannot do. It reads the PR description, the full conversation timeline, the CI/checks status, and the linked issue, then decides whether the PR clears PowerToys' process bar. Everything Phase 0 produces is drafted only. Full rules, the P1–P9 gate table, the compound-quality close signal, and per-gate reply templates are in references/phase0-context-review.md.

Disposition outcomes (Phase 0 → one of):

• Proceed — no gate tripped (or only Notes). Go to the code-review output.
• Ask — draft the specific request(s); review pauses on the author.
• Align first — duplicate/superseded/out-of-scope: draft a redirect to the canonical PR/issue.
• Recommend close — compound-quality or long-stale-with-author-owing: draft a polite close.

Always recommend, never auto-apply — labels/closes are maintainer actions gated by Step 10.

Code Review Workflow

These steps are the code-review engine. In self-check mode skip Steps 1–2c.

Convergence (Definition of done for Steps 5–6): the most recent freshly-requested Copilot review returned zero new inline comments, zero unresolved Copilot threads remain, and the worktree builds. Do not draft Step 9 suggestions until this holds.

Fork Configuration

Auto-detect these at the start of each session with scripts/Get-ForkConfig.ps1; verify on first run. The resolver prefers POWERTOYS_FORK_REPO, then the clone's non-Microsoft PowerToys remote, and verifies write permission. It may switch gh to the authenticated fork-owner account so fork branches and review PRs remain writable.

Available Scripts

References

• phase0-context-review.md — the context/process gates, dispositions, and reply templates
• prerequisites.md — fork, clone, Copilot review, and VS build-tool setup
• setup-and-mirror.md — Steps 0–2c: resume, mirror, worktree, rebase, diff validation
• copilot-review-loop.md — Steps 4–8: request, fix/push/resolve loop, summarize
• build-and-test.md — Steps 3, 7, 7b: local build, module chain, end-to-end tests
• migration-and-resume.md — move active reviews from older skill versions and resume durable loop state
• drafting-and-posting.md — Steps 9–10: suggestion format, freshness re-check, posting
• approval-dashboard.md — optional interactive UI for approving/holding/editing drafted actions across a multi-PR session
• batch-parallel.md — how to review 2+ PRs concurrently (sub-agent fan-out, build serialization, single-writer status, aggregation)