Add Review and Fix prompts for acceleration github issues (#43419)

## Summary of the Pull Request

This PR adds comprehensive GitHub PR review tooling infrastructure to
improve review efficiency through incremental review capabilities. The
tooling consists of PowerShell scripts that detect changes between
review iterations, enabling reviewers to focus only on modified files,
and AI prompt templates for structured PR and issue reviews.

**Key additions:**
- `.github/review-tools/`: PowerShell scripts for incremental PR review
detection
- `.github/prompts/`: AI prompt templates for PR reviews, issue reviews,
and issue fixes
- Copilot instructions documentation for review tools integration

## PR Checklist

- [ ] Closes: #xxx
- [x] **Communication:** I've discussed this with core contributors
already. If the work hasn't been agreed, this work might be rejected
- [x] **Tests:** Added/updated and all pass (N/A - tooling scripts with
manual validation)
- [x] **Localization:** All end-user-facing strings can be localized
(N/A - development tooling only)
- [x] **Dev docs:** Added/updated (comprehensive documentation in
`review-tools.instructions.md`)
- [ N/A ] **New binaries:** Added on the required places (N/A -
PowerShell scripts, no binaries)
- [ N/A ] **Documentation updated:** If checked, please file a pull
request on [our docs
repo](https://github.com/MicrosoftDocs/windows-uwp/tree/docs/hub/powertoys)
and link it here: #xxx (N/A - internal development tooling)

## Detailed Description of the Pull Request / Additional comments

### Review Tools Added (`.github/review-tools/`)

**Core Scripts:**
1. **`Get-PrIncrementalChanges.ps1`** (173 lines) - Compares last
reviewed commit SHA with current PR head to identify incremental
changes. Returns JSON with changed files, new commits, and review
recommendations. Handles scenarios: first review, no changes, force-push
detection, and incremental changes.

2. **`Test-IncrementalReview.ps1`** (170 lines) - Helper script to
preview incremental review detection before running full review.
Displays colored console output showing current vs last reviewed SHAs,
changed files, new commits, and recommended review strategy.

3. **`Migrate-ReviewToIncrementalFormat.ps1`** (206 lines) - One-time
migration script to add review metadata sections to existing
`00-OVERVIEW.md` files, enabling incremental review functionality for
legacy PR reviews.

4. **`Get-GitHubRawFile.ps1`** (91 lines) - Downloads file content from
GitHub repository at specific git reference for baseline comparison
during reviews. Supports optional line numbering.

5. **`Get-GitHubPrFilePatch.ps1`** (79 lines) - Fetches unified diff
(patch) for a specific file in a pull request using GitHub API.

6. **`review-tools.instructions.md`** (355 lines) - Comprehensive
documentation covering script usage, workflow integration, error
handling, best practices, and AI integration examples. Serves as Copilot
instructions for the review tools.

### AI Prompt Templates Added (`.github/prompts/`)

1. **`review-pr.prompt.md`** (200 lines) - Structured prompt for
comprehensive PR reviews with incremental review support
2. **`review-issue.prompt.md`** (158 lines) - Template for systematic
issue analysis and triage
3. **`fix-issue.prompt.md`** (71 lines) - Guided workflow for
implementing issue fixes
4. **Minor updates** to `create-commit-title.prompt.md` and
`create-pr-summary.prompt.md` for consistency

### Key Features

**Incremental Review Flow:**
- Initial review (iteration 1): Creates overview with metadata including
HEAD SHA
- Subsequent reviews (iteration 2+): Reads last reviewed SHA, detects
changes, reviews only modified files
- Smart step filtering: Skips irrelevant review steps based on file
types changed (e.g., skip Localization if no `.resx` files changed)

**Error Handling:**
- Detects force-push scenarios (last reviewed SHA no longer in history)
- Validates GitHub CLI authentication
- Provides detailed error messages with actionable solutions
- Exit code 1 on errors for automation compatibility

**Integration:**
- Works with GitHub CLI (`gh`) for API access
- JSON output for programmatic consumption
- Designed for AI-powered review systems (Copilot integration)
- Metadata tracking for context-aware suggestions

## Validation Steps Performed

**Manual Testing:**
1.  Verified all PowerShell scripts follow PSScriptAnalyzer rules
2.  Tested `Get-PrIncrementalChanges.ps1` with various scenarios:
   - First review (no previous SHA)
   - No changes (SHA matches current)
   - Force-push detection (SHA not in history)
   - Incremental changes (multiple commits and files)
3.  Validated `Test-IncrementalReview.ps1` output formatting and
accuracy
4.  Confirmed `Migrate-ReviewToIncrementalFormat.ps1` adds metadata
without corrupting existing reviews
5.  Tested GitHub API integration with `Get-GitHubRawFile.ps1` and
`Get-GitHubPrFilePatch.ps1`
6.  Verified documentation accuracy and completeness in
`review-tools.instructions.md`
7.  Validated prompt templates follow PowerToys repo conventions from
`.github/copilot-instructions.md`

**Dependencies Verified:**
- Requires PowerShell 7+ (or Windows PowerShell 5.1+)
- Requires GitHub CLI (`gh`) installed and authenticated
- All scripts include comprehensive help documentation (`Get-Help`
support)

**No Automated Tests:** These are development/CI tooling scripts used by
maintainers for PR reviews. Manual validation appropriate as they
interact with live GitHub API and require human judgment for review
quality assessment.
This commit is contained in:
Gordon Lam
2025-12-23 16:18:22 +08:00
committed by GitHub
parent afeeea671f
commit 534c411fd8
11 changed files with 1263 additions and 2 deletions

71
.github/prompts/fix-issue.prompt.md vendored Normal file
View File

@@ -0,0 +1,71 @@
---
mode: 'agent'
model: GPT-5-Codex (Preview)
description: " Execute the fix for a GitHub issue using the previously generated implementation plan. Apply code & tests directly in the repo. Output only a PR description (and optional manual steps)."
---
# DEPENDENCY
Source review prompt (for generating the implementation plan if missing):
- .github/prompts/review-issue.prompt.md
Required plan file (single source of truth):
- Generated Files/issueReview/{{issue_number}}/implementation-plan.md
## Dependency Handling
1) If `implementation-plan.md` exists → proceed.
2) If missing → run the review prompt:
- Invoke: `.github/prompts/review-issue.prompt.md`
- Pass: `issue_number={{issue_number}}`
- Then re-check for `implementation-plan.md`.
3) If still missing → stop and generate:
- `Generated Files/issueFix/{{issue_number}}/manual-steps.md` containing:
“implementation-plan.md not found; please run .github/prompts/review-issue.prompt.md for #{{issue_number}}.”
# GOAL
For **#{{issue_number}}**:
- Use implementation-plan.md as the single authority.
- Apply code and test changes directly in the repository.
- Produce a PR-ready description.
# OUTPUT FILES
1) Generated Files/issueFix/{{issue_number}}/pr-description.md
2) Generated Files/issueFix/{{issue_number}}/manual-steps.md # only if human interaction or external setup is required
# EXECUTION RULES
1) Read implementation-plan.md and execute:
- Layers & Files → edit/create as listed
- Pattern Choices → follow repository conventions
- Fundamentals (perf, security, compatibility, accessibility)
- Logging & Exceptions
- Telemetry (only if explicitly included in the plan)
- Risks & Mitigations
- Tests to Add
2) Locate affected files via `rg` or `git grep`.
3) Add/update tests to enforce the fixed behavior.
4) If any ambiguity exists, add:
// TODO(Human input needed): <clarification needed>
5) Verify locally: build & tests run successfully.
# pr-description.md should include:
- Title: `Fix: <short summary> (#{{issue_number}})`
- What changed and why the fix works
- Files or modules touched
- Risks & mitigations (implemented)
- Tests added/updated and how to run them
- Telemetry behavior (if applicable)
- Validation / reproduction steps
- `Closes #{{issue_number}}`
# manual-steps.md (only if needed)
- List required human actions: secrets, config, approvals, missing info, or code comments requiring human decisions.
# IMPORTANT
- Apply code and tests directly; do not produce patch files.
- Follow implementation-plan.md as the source of truth.
- Insert comments for human review where a decision or input is required.
- Use repository conventions and deterministic, minimal changes.
# FINALIZE
- Write pr-description.md
- Write manual-steps.md only if needed
- Print concise success message or note items requiring human interaction