Delete unused ps1

.github/actions/spell-check/expect.txt

@@ -378,6 +378,7 @@ devpal
 dfx
 DIALOGEX
 digicert
+diffs
 DINORMAL
 DISABLEASACTIONKEY
 DISABLENOSCROLL
@@ -959,6 +960,7 @@ mdtext
 mdtxt
 mdwn
 meme
+mcp
 memicmp
 MENUITEMINFO
 MENUITEMINFOW
@@ -1047,6 +1049,8 @@ multizone
 muxc
 MVPs
 mvvm
+myorg
+myrepo
 MVVMTK
 MWBEx
 MYICON
@@ -1262,6 +1266,7 @@ phwnd
 pici
 pidl
 PIDLIST
+PII
 pinfo
 pinvoke
 pipename
@@ -1457,6 +1462,7 @@ riid
 RKey
 RNumber
 rop
+rollups
 ROUNDSMALL
 ROWSETEXT
 rpcrt
@@ -2048,6 +2054,7 @@ xstyler
 XTimer
 XUP
 XVIRTUALSCREEN
+XXL
 xxxxxx
 YAxis
 ycombinator

.github/prompts/create-commit-title.prompt.md

@@ -1,6 +1,6 @@
 ---
 mode: 'agent'
-model: GPT-5-Codex (Preview)
+model: Claude Sonnet 4.5
 description: 'Generate an 80-character git commit title for the local diff.'
 ---
 

.github/prompts/create-pr-summary.prompt.md

@@ -1,6 +1,6 @@
 ---
 mode: 'agent'
-model: GPT-5-Codex (Preview)
+model: Claude Sonnet 4.5
 description: 'Generate a PowerToys-ready pull request description from the local diff.'
 ---
 

.github/prompts/fix-issue.prompt.md

@@ -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

.github/prompts/review-issue.prompt.md

@@ -0,0 +1,158 @@
+---
+mode: 'agent'
+model: Claude Sonnet 4.5
+description: "You are github issue review and planning expertise, Score (0–100) and write one Implementation Plan. Outputs: overview.md, implementation-plan.md."
+---
+
+# GOAL
+For **#{{issue_number}}** produce:
+1) `Generated Files/issueReview/{{issue_number}}/overview.md`
+2) `Generated Files/issueReview/{{issue_number}}/implementation-plan.md`
+
+## Inputs
+  figure out from the prompt on the 
+
+# CONTEXT (brief)
+Ground evidence using `gh issue view {{issue_number}} --json number,title,body,author,createdAt,updatedAt,state,labels,milestone,reactions,comments,linkedPullRequests`, and download the image for understand the context of the issue more.
+Locate source code in current workspace, but also free feel to use via `rg`/`git grep`. Link related issues/PRs.
+
+# OVERVIEW.MD
+## Summary
+Issue, state, milestone, labels. **Signals**: 👍/❤️/👎, comment count, last activity, linked PRs.
+
+## At-a-Glance Score Table
+Present all ratings in a compact table for quick scanning:
+
+| Dimension | Score | Assessment | Key Drivers |
+|-----------|-------|------------|-------------|
+| **A) Business Importance** | X/100 | Low/Medium/High | Top 2 factors with scores |
+| **B) Community Excitement** | X/100 | Low/Medium/High | Top 2 factors with scores |
+| **C) Technical Feasibility** | X/100 | Low/Medium/High | Top 2 factors with scores |
+| **D) Requirement Clarity** | X/100 | Low/Medium/High | Top 2 factors with scores |
+| **Overall Priority** | X/100 | Low/Medium/High/Critical | Average or weighted summary |
+| **Effort Estimate** | X days (T-shirt) | XS/S/M/L/XL/XXL/Epic | Type: bug/feature/chore |
+| **Similar Issues Found** | X open, Y closed | — | Quick reference to related work |
+| **Potential Assignees** | @username, @username | — | Top contributors to module |
+
+**Assessment bands**: 0-25 Low, 26-50 Medium, 51-75 High, 76-100 Critical
+
+## Ratings (0–100) — add evidence & short rationale
+### A) Business Importance
+- Labels (priority/security/regression): **≤35**
+- Milestone/roadmap: **≤25**
+- Customer/contract impact: **≤20**
+- Unblocks/platform leverage: **≤20**
+### B) Community Excitement
+- 👍+❤️ normalized: **≤45**
+- Comment volume & unique participants: **≤25**
+- Recent activity (≤30d): **≤15**
+- Duplicates/related issues: **≤15**
+### C) Technical Feasibility
+- Contained surface/clear seams: **≤30**
+- Existing patterns/utilities: **≤25**
+- Risk (perf/sec/compat) manageable: **≤25**
+- Testability & CI support: **≤20**
+### D) Requirement Clarity
+- Behavior/repro/constraints: **≤60**
+- Non-functionals (perf/sec/i18n/a11y): **≤25**
+- Decision owners/acceptance signals: **≤15**
+
+## Effort
+Days + **T-shirt** (XS 0.5–1d, S 1–2, M 2–4, L 4–7, XL 7–14, XXL 14–30, Epic >30).  
+Type/level: bug/feature/chore/docs/refactor/test-only; severity/value tier.
+
+## Suggested Actions
+Provide actionable recommendations for issue triage and assignment:
+
+### A) Requirement Clarification (if Clarity score <50)
+**When Requirement Clarity (Dimension D) is Medium or Low:**
+- Identify specific gaps in issue description: missing repro steps, unclear expected behavior, undefined acceptance criteria, missing non-functional requirements
+- Draft 3-5 clarifying questions to post as issue comment
+- Suggest additional information needed: screenshots, logs, environment details, OS version, PowerToys version, error messages
+- If behavior is ambiguous, propose 2-3 interpretation scenarios and ask reporter to confirm
+- Example questions:
+  - "Can you provide exact steps to reproduce this issue?"
+  - "What is the expected behavior vs. what you're actually seeing?"
+  - "Does this happen on Windows 10, 11, or both?"
+  - "Can you attach a screenshot or screen recording?"
+
+### B) Correct Label Suggestions
+- Analyze issue type, module, and severity to suggest missing or incorrect labels
+- Recommend labels from: `Issue-Bug`, `Issue-Feature`, `Issue-Docs`, `Issue-Task`, `Priority-High`, `Priority-Medium`, `Priority-Low`, `Needs-Triage`, `Needs-Author-Feedback`, `Product-<ModuleName>`, etc.
+- If Requirement Clarity is low (<50), add `Needs-Author-Feedback` label
+- If current labels are incorrect or incomplete, provide specific label changes with rationale
+
+### C) Find Similar Issues & Past Fixes
+- Search for similar issues using `gh issue list --search "keywords" --state all --json number,title,state,closedAt`
+- Identify patterns: duplicate issues, related bugs, or similar feature requests
+- For closed issues, find linked PRs that fixed them: check `linkedPullRequests` in issue data
+- Provide 3-5 examples of similar issues with format: `#<number> - <title> (closed by PR #<pr>)` or `(still open)`
+
+### D) Identify Subject Matter Experts
+- Use git blame/log to find who fixed similar issues in the past
+- Search for PR authors who touched relevant files: `git log --all --format='%aN' -- <file_paths> | sort | uniq -c | sort -rn | head -5`
+- Check issue/PR history for frequent contributors to the affected module
+- Suggest 2-3 potential assignees with context: `@<username> - <reason>` (e.g., "fixed similar rendering bug in #12345", "maintains FancyZones module")
+
+### E) Semantic Search for Related Work
+- Use semantic_search tool to find similar issues, code patterns, or past discussions
+- Search queries should include: issue keywords, module names, error messages, feature descriptions
+- Cross-reference semantic results with GitHub issue search for comprehensive coverage
+
+**Output format for Suggested Actions section in overview.md:**
+```markdown
+## Suggested Actions
+
+### Clarifying Questions (if Clarity <50)
+Post these questions as issue comment to gather missing information:
+1. <question>
+2. <question>
+3. <question>
+
+**Recommended label**: `Needs-Author-Feedback`
+
+### Label Recommendations
+- Add: `<label>` - <reason>
+- Remove: `<label>` - <reason>
+- Current labels are appropriate ✓
+
+### Similar Issues Found
+1. #<number> - <title> (<state>, closed by PR #<pr> on <date>)
+2. #<number> - <title> (<state>)
+...
+
+### Potential Assignees
+- @<username> - <reason>
+- @<username> - <reason>
+
+### Related Code/Discussions
+- <semantic search findings>
+```
+
+# IMPLEMENTATION-PLAN.MD
+1) **Problem Framing** — restate problem; current vs expected; scope boundaries.  
+2) **Layers & Files** — layers (UI/domain/data/infra/build). For each, list **files/dirs to modify** and **new files** (exact paths + why). Prefer repo patterns; cite examples/PRs.  
+3) **Pattern Choices** — reuse existing; if new, justify trade-offs & transition.  
+4) **Fundamentals** (brief plan or N/A + reason):
+- Performance (hot paths, allocs, caching/streaming)
+- Security (validation, authN/Z, secrets, SSRF/XSS/CSRF)
+- G11N/L10N (resources, number/date, pluralization)
+- Compatibility (public APIs, formats, OS/runtime/toolchain)
+- Extensibility (DI seams, options/flags, plugin points)
+- Accessibility (roles, labels, focus, keyboard, contrast)
+- SOLID & repo conventions (naming, folders, dependency direction)
+5) **Logging & Exception Handling**
+- Where to log; levels; structured fields; correlation/traces.
+- What to catch vs rethrow; retries/backoff; user-visible errors.
+- **Privacy**: never log secrets/PII; redaction policy.
+6) **Telemetry (optional — business metrics only)**
+- Events/metrics (name, when, props); success signal; privacy/sampling; dashboards/alerts.
+7) **Risks & Mitigations** — flags/canary/shadow-write/config guards.  
+8) **Task Breakdown (agent-ready)** — table (leave a blank line before the header so Markdown renders correctly):
+
+| Task | Intent | Files/Areas | Steps | Tests (brief) | Owner (Agent/Human) | Human interaction needed? (why) |
+|---|---|---|---|---|---|---|
+
+9) **Tests to Add (only)**
+- **Unit**: targets, cases (success/edge/error), mocks/fixtures, path, notes.  
+- **UI** (if applicable): flows, locator strategy, env/data/flags, path, flake mitigation.

.github/prompts/review-pr.prompt.md

@@ -0,0 +1,199 @@
+---
+mode: 'agent'
+model: Claude Sonnet 4.5
+description: "gh-driven PR review; per-step Markdown + machine-readable outputs"
+---
+
+# PR Review — gh + stepwise
+
+**Goal**: Given `{{pr_number}}`, run a *one-topic-per-step* review. Write files to `Generated Files/prReview/{{pr_number}}/` (replace `{{pr_number}}` with the integer). Emit machine‑readable blocks for a GitHub MCP to post review comments.
+
+## PR selection
+Resolve the target PR using these fallbacks in order:
+1. Parse the invocation text for an explicit identifier (first integer following patterns such as a leading hash and digits or the text `PR:` followed by digits).
+2. If no PR is found yet, locate the newest `Generated Files/prReview/_batch/batch-overview-*.md` file (highest timestamp in filename, fallback newest mtime) and take the first entry in its `## PRs` list whose review folder is missing `00-OVERVIEW.md` or contains `__error.flag`.
+3. If the batch file has no pending PRs, query assignments with `gh pr list --assignee @me --state open --json number,updatedAt --limit 20` and pick the most recently updated PR that does not already have a completed review folder.
+4. If still unknown, run `gh pr view --json number` in the current branch and use that result when it is unambiguous.
+5. If every step above fails, prompt the user for a PR number before proceeding.
+
+## Fetch PR data with `gh`
+- `gh pr view {{pr_number}} --json number,baseRefName,headRefName,baseRefOid,headRefOid,changedFiles,files`
+- `gh api repos/:owner/:repo/pulls/{{pr_number}}/files?per_page=250`  # patches for line mapping
+
+### Incremental review workflow
+1. **Check for existing review**: Read `Generated Files/prReview/{{pr_number}}/00-OVERVIEW.md`
+2. **Extract state**: Parse `Last reviewed SHA:` from review metadata section
+3. **Detect changes**: Run `Get-PrIncrementalChanges.ps1 -PullRequestNumber {{pr_number}} -LastReviewedCommitSha {{sha}}`
+4. **Analyze result**:
+   - `NeedFullReview: true` → Review all files in the PR
+   - `NeedFullReview: false` and `IsIncremental: true` → Review only files in `ChangedFiles` array
+   - `ChangedFiles` is empty → No changes, skip review (update iteration history with "No changes since last review")
+5. **Apply smart filtering**: Use the file patterns in smart step filtering table to skip irrelevant steps
+6. **Update metadata**: After completing review, save current `headRefOid` as `Last reviewed SHA:` in `00-OVERVIEW.md`
+
+### Reusable PowerShell scripts
+Scripts live in `.github/review-tools/` to avoid repeated manual approvals during PR reviews:
+
+| Script | Usage |
+| --- | --- |
+| `.github/review-tools/Get-GitHubRawFile.ps1` | Download a repository file at a given ref, optionally with line numbers. |
+| `.github/review-tools/Get-GitHubPrFilePatch.ps1` | Fetch the unified diff for a specific file within a pull request via `gh api`. |
+| `.github/review-tools/Get-PrIncrementalChanges.ps1` | Compare last reviewed SHA with current PR head to identify incremental changes. Returns JSON with changed files, new commits, and whether full review is needed. |
+| `.github/review-tools/Test-IncrementalReview.ps1` | Test helper to preview incremental review detection for a PR. Use before running full review to see what changed. |
+
+Always prefer these scripts (or new ones added under `.github/review-tools/`) over raw `gh api` or similar shell commands so the review flow does not trigger interactive approval prompts.
+
+## Output files
+Folder: `Generated Files/prReview/{{pr_number}}/`
+Files: `00-OVERVIEW.md`, `01-functionality.md`, `02-compatibility.md`, `03-performance.md`, `04-accessibility.md`, `05-security.md`, `06-localization.md`, `07-globalization.md`, `08-extensibility.md`, `09-solid-design.md`, `10-repo-patterns.md`, `11-docs-automation.md`, `12-code-comments.md`, `13-copilot-guidance.md` *(only if guidance md exists).* 
+- **Write-after-step rule:** Immediately after completing each TODO step, persist that step's markdown file before proceeding to the next. Generate `00-OVERVIEW.md` only after every step file has been refreshed for the current run.
+
+## Iteration management
+- Determine the current review iteration by reading `00-OVERVIEW.md` (look for `Review iteration:`). If missing, assume iteration `1`.
+- Extract the last reviewed SHA from `00-OVERVIEW.md` (look for `Last reviewed SHA:` in the review metadata section). If missing, this is iteration 1.
+- **Incremental review detection**:
+  1. Call `.github/review-tools/Get-PrIncrementalChanges.ps1 -PullRequestNumber {{pr_number}} -LastReviewedCommitSha {{last_sha}}` to get delta analysis.
+  2. Parse the JSON result to determine if incremental review is possible (`IsIncremental: true`, `NeedFullReview: false`).
+  3. If force-push detected or first review, proceed with full review of all changed files.
+  4. If incremental, review only the files listed in `ChangedFiles` array and apply smart step filtering (see below).
+- Increment the iteration for each review run and propagate the new value to all step files and the overview.
+- Preserve prior iteration notes by keeping/expanding an `## Iteration history` section in each markdown file, appending the newest summary under `### Iteration <N>`.
+- Summaries should capture key deltas since the previous iteration so reruns can pick up context quickly.
+- **After review completion**, update `Last reviewed SHA:` in `00-OVERVIEW.md` with the current `headRefOid` and update the timestamp.
+
+### Smart step filtering (incremental reviews only)
+When performing incremental review, skip steps that are irrelevant based on changed file types:
+
+| File pattern | Required steps | Skippable steps |
+| --- | --- | --- |
+| `**/*.cs`, `**/*.cpp`, `**/*.h` | Functionality, Compatibility, Performance, Security, SOLID, Repo patterns, Code comments | (depends on files) |
+| `**/*.resx`, `**/Resources/*.xaml` | Localization, Globalization | Most others |
+| `**/*.md` (docs) | Docs & automation | Most others (unless copilot guidance) |
+| `**/*copilot*.md`, `.github/prompts/*.md` | Copilot guidance, Docs & automation | Most others |
+| `**/*.csproj`, `**/*.vcxproj`, `**/packages.config` | Compatibility, Security, Repo patterns | Localization, Globalization, Accessibility |
+| `**/UI/**`, `**/*View.xaml` | Accessibility, Localization | Performance (unless perf-sensitive controls) |
+
+**Default**: If uncertain or files span multiple categories, run all applicable steps. When in doubt, be conservative and review more rather than less.
+
+## TODO steps (one concern each)
+1) Functionality
+2) Compatibility
+3) Performance
+4) Accessibility
+5) Security
+6) Localization
+7) Globalization
+8) Extensibility
+9) SOLID principles
+10) Repo patterns
+11) Docs & automation coverage for the changes
+12) Code comments
+13) Copilot guidance (conditional): if changed folders contain `*copilot*.md` or `.github/prompts/*.md`, review diffs **against** that guidance and write `13-copilot-guidance.md` (omit if none).
+
+## Per-step file template (use verbatim)
+```md
+# <STEP TITLE>
+**PR:** (populate with PR identifier) — Base:<baseRefName> Head:<headRefName>
+**Review iteration:** ITERATION
+
+## Iteration history
+- Maintain subsections titled `### Iteration N` in reverse chronological order (append the latest at the top) with 2–4 bullet highlights.
+
+### Iteration ITERATION
+- <Latest key point 1>
+- <Latest key point 2>
+
+## Checks executed
+- List the concrete checks for *this step only* (5–10 bullets).
+
+## Findings
+(If none, write **None**. Defaults have one or more blocks:)
+
+```mcp-review-comment
+{"file":"relative/path.ext","start_line":123,"end_line":125,"severity":"high|medium|low|info","tags":["<step-slug>","pr-tag-here"],"related_files":["optional/other/file1"],"body":"Problem → Why it matters → Concrete fix. If spans multiple files, name them here."}
+```
+Use the second tag to encode the PR number.
+
+```
+## Overview file (`00-OVERVIEW.md`) template
+```md
+# PR Review Overview — (populate with PR identifier)
+**Review iteration:** ITERATION
+**Changed files:** <n> | **High severity issues:** <count>
+
+## Review metadata
+**Last reviewed SHA:** <headRefOid from gh pr view>
+**Last review timestamp:** <ISO8601 timestamp>
+**Review mode:** <Full|Incremental (N files changed since iteration X)>
+**Base ref:** <baseRefName>
+**Head ref:** <headRefName>
+
+## Step results
+Write lines like: `01 Functionality — <OK|Issues|Skipped> (see 01-functionality.md)` … through step 13.
+Mark steps as "Skipped" when using incremental review smart filtering.
+
+## Iteration history
+- Maintain subsections titled `### Iteration N` mirroring the per-step convention with concise deltas and cross-links to the relevant step files.
+- For incremental reviews, list the specific files that changed and which commits were added.
+```
+
+## Line numbers & multi‑file issues
+- Map head‑side lines from `patch` hunks (`@@ -a,b +c,d @@` → new lines `+c..+c+d-1`).
+- For cross‑file issues: set the primary `"file"`, list others in `"related_files"`, and name them in `"body"`.
+
+## Posting (for MCP)
+- Parse all ```mcp-review-comment``` blocks across step files and post as PR review comments.
+- If posting isn’t available, still write all files.
+
+## Constraint
+Read/analyze only; don't modify code. Keep comments small, specific, and fix‑oriented.
+
+**Testing**: Use `.github/review-tools/Test-IncrementalReview.ps1 -PullRequestNumber 42374` to preview incremental detection before running full review.
+
+## Scratch cache for large PRs
+
+Create a local scratch workspace to progressively summarize diffs and reload state across runs.
+
+### Paths
+- Root: `Generated Files/prReview/{{pr_number}}/__tmp/`
+- Files:
+  - `index.jsonl` — append-only JSON Lines index of artifacts.
+  - `todo-queue.json` — pending items (files/chunks/steps).
+  - `rollup-<step>-v<N>.md` — iterative per-step aggregates.
+  - `file-<hash>.txt` — optional saved chunk text (when needed).
+
+### JSON schema (per line in `index.jsonl`)
+```json
+{"type":"chunk|summary|issue|crosslink",
+ "path":"relative/file.ext","chunk_id":"f-12","step":"functionality|compatibility|...",
+ "base_sha":"...", "head_sha":"...", "range":[start,end], "version":1,
+ "notes":"short text or key:value map", "created_utc":"ISO8601"}
+```
+
+### Phases (stateful; resume-safe)
+0. **Discover** PR + SHAs: `gh pr view <PR> --json baseRefName,headRefName,baseRefOid,headRefOid,files`.
+1. **Chunk** each changed file (head): split into ~300–600 LOC or ~4k chars; stable `chunk_id` = hash(path+start).
+   - Save `chunk` records. Optionally write `file-<hash>.txt` for expensive chunks.
+2. **Summarize** per chunk: intent, APIs, risks per TODO step; emit `summary` records (≤600 tokens each).
+3. **Issues**: convert findings to machine-readable blocks and emit `issue` records (later rendered to step MD).
+4. **Rollups**: build/update `rollup-<step>-v<N>.md` from `summary`+`issue`. Keep prior versions.
+5. **Finalize**: write per-step files + `00-OVERVIEW.md` from rollups. Post comments via MCP if available.
+
+### Re-use & token limits
+- Always **reload** `index.jsonl` first; skip chunks with same `head_sha` and `range`.
+- **Incremental review optimization**: When `Get-PrIncrementalChanges.ps1` returns a subset of changed files, load only chunks from those files. Reuse existing chunks/summaries for unchanged files.
+- Prefer re-summarizing only changed chunks; merge chunk summaries → file summaries → step rollups.
+- When context is tight, load only the minimal chunk text (or its saved `file-<hash>.txt`) needed for a comment.
+
+### Original vs diff
+- Fetch base content when needed: prefer `git show <baseRefName>:<path>`; fallback `gh api repos/:owner/:repo/contents/<path>?ref=<base_sha>` (base64).
+- Use patch hunks from `gh api .../pulls/<PR>/files` to compute **head** line numbers.
+
+### Queue-driven loop
+- Seed `todo-queue.json` with all changed files.
+- Process: chunk → summarize → detect issues → roll up.
+- Append to `index.jsonl` after each step; never rewrite previous lines (append-only).
+
+### Hygiene
+- `__tmp/` is implementation detail; do not include in final artifacts.
+- It is safe to delete to force a clean pass; the next run rebuilds it.

.github/review-tools/Get-GitHubPrFilePatch.ps1

@@ -0,0 +1,79 @@
+<#
+.SYNOPSIS
+    Retrieves the unified diff patch for a specific file in a GitHub pull request.
+
+.DESCRIPTION
+    This script fetches the patch content (unified diff format) for a specified file
+    within a pull request. It uses the GitHub CLI (gh) to query the GitHub API and
+    retrieve file change information.
+
+.PARAMETER PullRequestNumber
+    The pull request number to query.
+
+.PARAMETER FilePath
+    The relative path to the file in the repository (e.g., "src/modules/main.cpp").
+
+.PARAMETER RepositoryOwner
+    The GitHub repository owner. Defaults to "microsoft".
+
+.PARAMETER RepositoryName
+    The GitHub repository name. Defaults to "PowerToys".
+
+.EXAMPLE
+    .\Get-GitHubPrFilePatch.ps1 -PullRequestNumber 42374 -FilePath "src/modules/cmdpal/main.cpp"
+    Retrieves the patch for main.cpp in PR #42374.
+
+.EXAMPLE
+    .\Get-GitHubPrFilePatch.ps1 -PullRequestNumber 42374 -FilePath "README.md" -RepositoryOwner "myorg" -RepositoryName "myrepo"
+    Retrieves the patch from a different repository.
+
+.NOTES
+    Requires GitHub CLI (gh) to be installed and authenticated.
+    Run 'gh auth login' if not already authenticated.
+
+.LINK
+    https://cli.github.com/
+#>
+
+[CmdletBinding()]
+param(
+    [Parameter(Mandatory = $true, HelpMessage = "Pull request number")]
+    [int]$PullRequestNumber,
+
+    [Parameter(Mandatory = $true, HelpMessage = "Relative path to the file in the repository")]
+    [string]$FilePath,
+
+    [Parameter(Mandatory = $false, HelpMessage = "Repository owner")]
+    [string]$RepositoryOwner = "microsoft",
+
+    [Parameter(Mandatory = $false, HelpMessage = "Repository name")]
+    [string]$RepositoryName = "PowerToys"
+)
+
+# Construct GitHub API path for pull request files
+$apiPath = "repos/$RepositoryOwner/$RepositoryName/pulls/$PullRequestNumber/files?per_page=250"
+
+# Query GitHub API to get all files in the pull request
+try {
+    $pullRequestFiles = gh api $apiPath | ConvertFrom-Json
+} catch {
+    Write-Error "Failed to query GitHub API for PR #$PullRequestNumber. Ensure gh CLI is authenticated. Details: $_"
+    exit 1
+}
+
+# Find the matching file in the pull request
+$matchedFile = $pullRequestFiles | Where-Object { $_.filename -eq $FilePath }
+
+if (-not $matchedFile) {
+    Write-Error "File '$FilePath' not found in PR #$PullRequestNumber."
+    exit 1
+}
+
+# Check if patch content exists
+if (-not $matchedFile.patch) {
+    Write-Warning "File '$FilePath' has no patch content (possibly binary or too large)."
+    return
+}
+
+# Output the patch content
+$matchedFile.patch

.github/review-tools/Get-GitHubRawFile.ps1

@@ -0,0 +1,91 @@
+<#
+.SYNOPSIS
+    Downloads and displays the content of a file from a GitHub repository at a specific git reference.
+
+.DESCRIPTION
+    This script fetches the raw content of a file from a GitHub repository using GitHub's raw content API.
+    It can optionally display line numbers and supports any valid git reference (branch, tag, or commit SHA).
+
+.PARAMETER FilePath
+    The relative path to the file in the repository (e.g., "src/modules/main.cpp").
+
+.PARAMETER GitReference
+    The git reference (branch name, tag, or commit SHA) to fetch the file from. Defaults to "main".
+
+.PARAMETER RepositoryOwner
+    The GitHub repository owner. Defaults to "microsoft".
+
+.PARAMETER RepositoryName
+    The GitHub repository name. Defaults to "PowerToys".
+
+.PARAMETER ShowLineNumbers
+    When specified, displays line numbers before each line of content.
+
+.PARAMETER StartLineNumber
+    The starting line number to use when ShowLineNumbers is enabled. Defaults to 1.
+
+.EXAMPLE
+    .\Get-GitHubRawFile.ps1 -FilePath "README.md" -GitReference "main"
+    Downloads and displays the README.md file from the main branch.
+
+.EXAMPLE
+    .\Get-GitHubRawFile.ps1 -FilePath "src/runner/main.cpp" -GitReference "dev/feature-branch" -ShowLineNumbers
+    Downloads main.cpp from a feature branch and displays it with line numbers.
+
+.EXAMPLE
+    .\Get-GitHubRawFile.ps1 -FilePath "LICENSE" -GitReference "abc123def" -ShowLineNumbers -StartLineNumber 10
+    Downloads the LICENSE file from a specific commit and displays it with line numbers starting at 10.
+
+.NOTES
+    Requires internet connectivity to access GitHub's raw content API.
+    Does not require GitHub CLI authentication for public repositories.
+
+.LINK
+    https://docs.github.com/en/rest/repos/contents
+#>
+
+[CmdletBinding()]
+param(
+    [Parameter(Mandatory = $true, HelpMessage = "Relative path to the file in the repository")]
+    [string]$FilePath,
+
+    [Parameter(Mandatory = $false, HelpMessage = "Git reference (branch, tag, or commit SHA)")]
+    [string]$GitReference = "main",
+
+    [Parameter(Mandatory = $false, HelpMessage = "Repository owner")]
+    [string]$RepositoryOwner = "microsoft",
+
+    [Parameter(Mandatory = $false, HelpMessage = "Repository name")]
+    [string]$RepositoryName = "PowerToys",
+
+    [Parameter(Mandatory = $false, HelpMessage = "Display line numbers before each line")]
+    [switch]$ShowLineNumbers,
+
+    [Parameter(Mandatory = $false, HelpMessage = "Starting line number for display")]
+    [int]$StartLineNumber = 1
+)
+
+# Construct the raw content URL
+$rawContentUrl = "https://raw.githubusercontent.com/$RepositoryOwner/$RepositoryName/$GitReference/$FilePath"
+
+# Fetch the file content from GitHub
+try {
+    $response = Invoke-WebRequest -UseBasicParsing -Uri $rawContentUrl
+} catch {
+    Write-Error "Failed to fetch file from $rawContentUrl. Details: $_"
+    exit 1
+}
+
+# Split content into individual lines
+$contentLines = $response.Content -split "`n"
+
+# Display the content with or without line numbers
+if ($ShowLineNumbers) {
+    $currentLineNumber = $StartLineNumber
+    foreach ($line in $contentLines) {
+        Write-Output ("{0:d4}: {1}" -f $currentLineNumber, $line)
+        $currentLineNumber++
+    }
+} else {
+    $contentLines | ForEach-Object { Write-Output $_ }
+}

.github/review-tools/Get-PrIncrementalChanges.ps1

@@ -0,0 +1,173 @@
+<#
+.SYNOPSIS
+    Detects changes between the last reviewed commit and current head of a pull request.
+
+.DESCRIPTION
+    This script compares a previously reviewed commit SHA with the current head of a pull request
+    to determine what has changed. It helps enable incremental reviews by identifying new commits
+    and modified files since the last review iteration.
+
+    The script handles several scenarios:
+    - First review (no previous SHA provided)
+    - No changes (current SHA matches last reviewed SHA)
+    - Force-push detected (last reviewed SHA no longer in history)
+    - Incremental changes (new commits added since last review)
+
+.PARAMETER PullRequestNumber
+    The pull request number to analyze.
+
+.PARAMETER LastReviewedCommitSha
+    The commit SHA that was last reviewed. If omitted, this is treated as a first review.
+
+.PARAMETER RepositoryOwner
+    The GitHub repository owner. Defaults to "microsoft".
+
+.PARAMETER RepositoryName
+    The GitHub repository name. Defaults to "PowerToys".
+
+.OUTPUTS
+    JSON object containing:
+    - PullRequestNumber: The PR number being analyzed
+    - CurrentHeadSha: The current head commit SHA
+    - LastReviewedSha: The last reviewed commit SHA (if provided)
+    - BaseRefName: Base branch name
+    - HeadRefName: Head branch name
+    - IsIncremental: Boolean indicating if incremental review is possible
+    - NeedFullReview: Boolean indicating if a full review is required
+    - ChangedFiles: Array of files that changed (filename, status, additions, deletions)
+    - NewCommits: Array of commits added since last review (sha, message, author, date)
+    - Summary: Human-readable description of changes
+
+.EXAMPLE
+    .\Get-PrIncrementalChanges.ps1 -PullRequestNumber 42374
+    Analyzes PR #42374 with no previous review (first review scenario).
+
+.EXAMPLE
+    .\Get-PrIncrementalChanges.ps1 -PullRequestNumber 42374 -LastReviewedCommitSha "abc123def456"
+    Compares current PR state against the last reviewed commit to identify incremental changes.
+
+.EXAMPLE
+    $changes = .\Get-PrIncrementalChanges.ps1 -PullRequestNumber 42374 -LastReviewedCommitSha "abc123" | ConvertFrom-Json
+    if ($changes.IsIncremental) { Write-Host "Can perform incremental review" }
+    Captures the output as a PowerShell object for further processing.
+
+.NOTES
+    Requires GitHub CLI (gh) to be installed and authenticated.
+    Run 'gh auth login' if not already authenticated.
+
+.LINK
+    https://cli.github.com/
+#>
+
+[CmdletBinding()]
+param(
+    [Parameter(Mandatory = $true, HelpMessage = "Pull request number")]
+    [int]$PullRequestNumber,
+
+    [Parameter(Mandatory = $false, HelpMessage = "Commit SHA that was last reviewed")]
+    [string]$LastReviewedCommitSha,
+
+    [Parameter(Mandatory = $false, HelpMessage = "Repository owner")]
+    [string]$RepositoryOwner = "microsoft",
+
+    [Parameter(Mandatory = $false, HelpMessage = "Repository name")]
+    [string]$RepositoryName = "PowerToys"
+)
+
+# Fetch current pull request state from GitHub
+try {
+    $pullRequestData = gh pr view $PullRequestNumber --json headRefOid,headRefName,baseRefName,baseRefOid | ConvertFrom-Json
+} catch {
+    Write-Error "Failed to fetch PR #$PullRequestNumber details. Details: $_"
+    exit 1
+}
+
+$currentHeadSha = $pullRequestData.headRefOid
+$baseRefName = $pullRequestData.baseRefName
+$headRefName = $pullRequestData.headRefName
+
+# Initialize result object
+$analysisResult = @{
+    PullRequestNumber = $PullRequestNumber
+    CurrentHeadSha = $currentHeadSha
+    BaseRefName = $baseRefName
+    HeadRefName = $headRefName
+    LastReviewedSha = $LastReviewedCommitSha
+    IsIncremental = $false
+    NeedFullReview = $true
+    ChangedFiles = @()
+    NewCommits = @()
+    Summary = ""
+}
+
+# Scenario 1: First review (no previous SHA provided)
+if ([string]::IsNullOrWhiteSpace($LastReviewedCommitSha)) {
+    $analysisResult.Summary = "Initial review - no previous iteration found"
+    $analysisResult.NeedFullReview = $true
+    return $analysisResult | ConvertTo-Json -Depth 10
+}
+
+# Scenario 2: No changes since last review
+if ($currentHeadSha -eq $LastReviewedCommitSha) {
+    $analysisResult.Summary = "No changes since last review (SHA: $currentHeadSha)"
+    $analysisResult.NeedFullReview = $false
+    $analysisResult.IsIncremental = $true
+    return $analysisResult | ConvertTo-Json -Depth 10
+}
+
+# Scenario 3: Check for force-push (last reviewed SHA no longer exists in history)
+try {
+    $null = gh api "repos/$RepositoryOwner/$RepositoryName/commits/$LastReviewedCommitSha" 2>&1
+    if ($LASTEXITCODE -ne 0) {
+        # SHA not found - likely force-push or branch rewrite
+        $analysisResult.Summary = "Force-push detected - last reviewed SHA $LastReviewedCommitSha no longer exists. Full review required."
+        $analysisResult.NeedFullReview = $true
+        return $analysisResult | ConvertTo-Json -Depth 10
+    }
+} catch {
+    $analysisResult.Summary = "Cannot verify last reviewed SHA $LastReviewedCommitSha - assuming force-push. Full review required."
+    $analysisResult.NeedFullReview = $true
+    return $analysisResult | ConvertTo-Json -Depth 10
+}
+
+# Scenario 4: Get incremental changes between last reviewed SHA and current head
+try {
+    $compareApiPath = "repos/$RepositoryOwner/$RepositoryName/compare/$LastReviewedCommitSha...$currentHeadSha"
+    $comparisonData = gh api $compareApiPath | ConvertFrom-Json
+    
+    # Extract new commits information
+    $analysisResult.NewCommits = $comparisonData.commits | ForEach-Object {
+        @{
+            Sha = $_.sha.Substring(0, 7)
+            Message = $_.commit.message.Split("`n")[0]  # First line only
+            Author = $_.commit.author.name
+            Date = $_.commit.author.date
+        }
+    }
+    
+    # Extract changed files information
+    $analysisResult.ChangedFiles = $comparisonData.files | ForEach-Object {
+        @{
+            Filename = $_.filename
+            Status = $_.status  # added, modified, removed, renamed
+            Additions = $_.additions
+            Deletions = $_.deletions
+            Changes = $_.changes
+        }
+    }
+    
+    $fileCount = $analysisResult.ChangedFiles.Count
+    $commitCount = $analysisResult.NewCommits.Count
+    
+    $analysisResult.IsIncremental = $true
+    $analysisResult.NeedFullReview = $false
+    $analysisResult.Summary = "Incremental review: $commitCount new commit(s), $fileCount file(s) changed since SHA $($LastReviewedCommitSha.Substring(0, 7))"
+    
+} catch {
+    Write-Error "Failed to compare commits. Details: $_"
+    $analysisResult.Summary = "Error comparing commits - defaulting to full review"
+    $analysisResult.NeedFullReview = $true
+}
+
+# Return the analysis result as JSON
+return $analysisResult | ConvertTo-Json -Depth 10

.github/review-tools/Test-IncrementalReview.ps1

@@ -0,0 +1,170 @@
+<#
+.SYNOPSIS
+    Tests and previews incremental review detection for a pull request.
+
+.DESCRIPTION
+    This helper script validates the incremental review detection logic by analyzing an existing
+    PR review folder. It reads the last reviewed SHA from the overview file, compares it with
+    the current PR state, and displays detailed information about what has changed.
+    
+    This is useful for:
+    - Testing the incremental review system before running a full review
+    - Understanding what changed since the last review iteration
+    - Verifying that review metadata was properly recorded
+
+.PARAMETER PullRequestNumber
+    The pull request number to test incremental review detection for.
+
+.PARAMETER RepositoryOwner
+    The GitHub repository owner. Defaults to "microsoft".
+
+.PARAMETER RepositoryName
+    The GitHub repository name. Defaults to "PowerToys".
+
+.OUTPUTS
+    Colored console output displaying:
+    - Current and last reviewed commit SHAs
+    - Whether incremental review is possible
+    - List of new commits since last review
+    - List of changed files with status indicators
+    - Recommended review strategy
+
+.EXAMPLE
+    .\Test-IncrementalReview.ps1 -PullRequestNumber 42374
+    Tests incremental review detection for PR #42374.
+
+.EXAMPLE
+    .\Test-IncrementalReview.ps1 -PullRequestNumber 42374 -RepositoryOwner "myorg" -RepositoryName "myrepo"
+    Tests incremental review for a PR in a different repository.
+
+.NOTES
+    Requires GitHub CLI (gh) to be installed and authenticated.
+    Run 'gh auth login' if not already authenticated.
+    
+    Prerequisites:
+    - PR review folder must exist at "Generated Files\prReview\{PRNumber}"
+    - 00-OVERVIEW.md must exist in the review folder
+    - For incremental detection, overview must contain "Last reviewed SHA" metadata
+
+.LINK
+    https://cli.github.com/
+#>
+
+[CmdletBinding()]
+param(
+    [Parameter(Mandatory = $true, HelpMessage = "Pull request number to test")]
+    [int]$PullRequestNumber,
+
+    [Parameter(Mandatory = $false, HelpMessage = "Repository owner")]
+    [string]$RepositoryOwner = "microsoft",
+
+    [Parameter(Mandatory = $false, HelpMessage = "Repository name")]
+    [string]$RepositoryName = "PowerToys"
+)
+
+# Resolve paths to review folder and overview file
+$repositoryRoot = Split-Path (Split-Path $PSScriptRoot -Parent) -Parent
+$reviewFolderPath = Join-Path $repositoryRoot "Generated Files\prReview\$PullRequestNumber"
+$overviewFilePath = Join-Path $reviewFolderPath "00-OVERVIEW.md"
+
+Write-Host "=== Testing Incremental Review for PR #$PullRequestNumber ===" -ForegroundColor Cyan
+Write-Host ""
+
+# Check if review folder exists
+if (-not (Test-Path $reviewFolderPath)) {
+    Write-Host "❌ Review folder not found: $reviewFolderPath" -ForegroundColor Red
+    Write-Host "This appears to be a new review (iteration 1)" -ForegroundColor Yellow
+    exit 0
+}
+
+# Check if overview file exists
+if (-not (Test-Path $overviewFilePath)) {
+    Write-Host "❌ Overview file not found: $overviewFilePath" -ForegroundColor Red
+    Write-Host "This appears to be an incomplete review" -ForegroundColor Yellow
+    exit 0
+}
+
+# Read overview file and extract last reviewed SHA
+Write-Host "📄 Reading overview file..." -ForegroundColor Green
+$overviewFileContent = Get-Content $overviewFilePath -Raw
+
+if ($overviewFileContent -match '\*\*Last reviewed SHA:\*\*\s+(\w+)') {
+    $lastReviewedSha = $Matches[1]
+    Write-Host "✅ Found last reviewed SHA: $lastReviewedSha" -ForegroundColor Green
+} else {
+    Write-Host "⚠️  No 'Last reviewed SHA' found in overview - this may be an old format" -ForegroundColor Yellow
+    Write-Host "Proceeding without incremental detection (full review will be needed)" -ForegroundColor Yellow
+    exit 0
+}
+
+Write-Host ""
+Write-Host "🔍 Running incremental change detection..." -ForegroundColor Cyan
+
+# Call the incremental changes detection script
+$incrementalChangesScriptPath = Join-Path $PSScriptRoot "Get-PrIncrementalChanges.ps1"
+if (-not (Test-Path $incrementalChangesScriptPath)) {
+    Write-Host "❌ Script not found: $incrementalChangesScriptPath" -ForegroundColor Red
+    exit 1
+}
+
+try {
+    $analysisResult = & $incrementalChangesScriptPath `
+        -PullRequestNumber $PullRequestNumber `
+        -LastReviewedCommitSha $lastReviewedSha `
+        -RepositoryOwner $RepositoryOwner `
+        -RepositoryName $RepositoryName | ConvertFrom-Json
+    
+    # Display analysis results
+    Write-Host ""
+    Write-Host "=== Incremental Review Analysis ===" -ForegroundColor Cyan
+    Write-Host "Current HEAD SHA: $($analysisResult.CurrentHeadSha)" -ForegroundColor White
+    Write-Host "Last reviewed SHA: $($analysisResult.LastReviewedSha)" -ForegroundColor White
+    Write-Host "Base branch: $($analysisResult.BaseRefName)" -ForegroundColor White
+    Write-Host "Head branch: $($analysisResult.HeadRefName)" -ForegroundColor White
+    Write-Host ""
+    Write-Host "Is incremental? $($analysisResult.IsIncremental)" -ForegroundColor $(if ($analysisResult.IsIncremental) { "Green" } else { "Yellow" })
+    Write-Host "Need full review? $($analysisResult.NeedFullReview)" -ForegroundColor $(if ($analysisResult.NeedFullReview) { "Yellow" } else { "Green" })
+    Write-Host ""
+    Write-Host "Summary: $($analysisResult.Summary)" -ForegroundColor Cyan
+    Write-Host ""
+    
+    # Display new commits if any
+    if ($analysisResult.NewCommits -and $analysisResult.NewCommits.Count -gt 0) {
+        Write-Host "📝 New commits ($($analysisResult.NewCommits.Count)):" -ForegroundColor Green
+        foreach ($commit in $analysisResult.NewCommits) {
+            Write-Host "  - $($commit.Sha): $($commit.Message)" -ForegroundColor Gray
+        }
+        Write-Host ""
+    }
+    
+    # Display changed files if any
+    if ($analysisResult.ChangedFiles -and $analysisResult.ChangedFiles.Count -gt 0) {
+        Write-Host "📁 Changed files ($($analysisResult.ChangedFiles.Count)):" -ForegroundColor Green
+        foreach ($file in $analysisResult.ChangedFiles) {
+            $statusDisplayColor = switch ($file.Status) {
+                "added"    { "Green" }
+                "removed"  { "Red" }
+                "modified" { "Yellow" }
+                "renamed"  { "Cyan" }
+                default    { "White" }
+            }
+            Write-Host "  - [$($file.Status)] $($file.Filename) (+$($file.Additions)/-$($file.Deletions))" -ForegroundColor $statusDisplayColor
+        }
+        Write-Host ""
+    }
+    
+    # Suggest review strategy based on analysis
+    Write-Host "=== Recommended Review Strategy ===" -ForegroundColor Cyan
+    if ($analysisResult.NeedFullReview) {
+        Write-Host "🔄 Full review recommended" -ForegroundColor Yellow
+    } elseif ($analysisResult.IsIncremental -and ($analysisResult.ChangedFiles.Count -eq 0)) {
+        Write-Host "✅ No changes detected - no review needed" -ForegroundColor Green
+    } elseif ($analysisResult.IsIncremental) {
+        Write-Host "⚡ Incremental review possible - review only changed files" -ForegroundColor Green
+        Write-Host "💡 Consider applying smart step filtering based on file types" -ForegroundColor Cyan
+    }
+    
+} catch {
+    Write-Host "❌ Error running incremental change detection: $_" -ForegroundColor Red
+    exit 1
+}

.github/review-tools/review-tools.instructions.md

@@ -0,0 +1,313 @@
+---
+description: PowerShell scripts for efficient PR reviews in PowerToys repository
+applyTo: '**'
+---
+
+# PR Review Tools - Reference Guide
+
+PowerShell scripts to support efficient and incremental pull request reviews in the PowerToys repository.
+
+## Quick Start
+
+### Prerequisites
+- PowerShell 7+ (or Windows PowerShell 5.1+)
+- GitHub CLI (`gh`) installed and authenticated (`gh auth login`)
+- Access to the PowerToys repository
+
+### Testing Your Setup
+
+Run the full test suite (recommended):
+```powershell
+cd "d:\PowerToys-00c1\.github\review-tools"
+.\Run-ReviewToolsTests.ps1
+```
+
+Expected: 9-10 tests passing
+
+### Individual Script Tests
+
+**Test incremental change detection:**
+```powershell
+.\Get-PrIncrementalChanges.ps1 -PullRequestNumber 42374
+```
+Expected: JSON output showing review analysis
+
+**Preview incremental review:**
+```powershell
+.\Test-IncrementalReview.ps1 -PullRequestNumber 42374
+```
+Expected: Analysis showing current vs last reviewed SHA
+
+**Fetch file content:**
+```powershell
+.\Get-GitHubRawFile.ps1 -FilePath "README.md" -GitReference "main"
+```
+Expected: README content displayed
+
+**Get PR file patch:**
+```powershell
+.\Get-GitHubPrFilePatch.ps1 -PullRequestNumber 42374 -FilePath ".github/actions/spell-check/expect.txt"
+```
+Expected: Unified diff output
+
+## Available Scripts
+
+### Get-GitHubRawFile.ps1
+
+Downloads and displays file content from a GitHub repository at a specific git reference.
+
+**Purpose:** Retrieve baseline file content for comparison during PR reviews.
+
+**Parameters:**
+- `FilePath` (required): Relative path to file in repository
+- `GitReference` (optional): Git ref (branch, tag, SHA). Default: "main"
+- `RepositoryOwner` (optional): Repository owner. Default: "microsoft"
+- `RepositoryName` (optional): Repository name. Default: "PowerToys"
+- `ShowLineNumbers` (switch): Prefix each line with line number
+- `StartLineNumber` (optional): Starting line number when using `-ShowLineNumbers`. Default: 1
+
+**Usage:**
+```powershell
+.\Get-GitHubRawFile.ps1 -FilePath "src/runner/main.cpp" -GitReference "main" -ShowLineNumbers
+```
+
+### Get-GitHubPrFilePatch.ps1
+
+Fetches the unified diff (patch) for a specific file in a pull request.
+
+**Purpose:** Get the exact changes made to a file in a PR for detailed review.
+
+**Parameters:**
+- `PullRequestNumber` (required): Pull request number
+- `FilePath` (required): Relative path to file in the PR
+- `RepositoryOwner` (optional): Repository owner. Default: "microsoft"
+- `RepositoryName` (optional): Repository name. Default: "PowerToys"
+
+**Usage:**
+```powershell
+.\Get-GitHubPrFilePatch.ps1 -PullRequestNumber 42374 -FilePath "src/modules/cmdpal/main.cpp"
+```
+
+**Output:** Unified diff showing changes made to the file.
+
+### Get-PrIncrementalChanges.ps1
+
+Compares the last reviewed commit with the current PR head to identify incremental changes.
+
+**Purpose:** Enable efficient incremental reviews by detecting what changed since the last review iteration.
+
+**Parameters:**
+- `PullRequestNumber` (required): Pull request number
+- `LastReviewedCommitSha` (optional): SHA of the commit that was last reviewed. If omitted, assumes first review.
+- `RepositoryOwner` (optional): Repository owner. Default: "microsoft"
+- `RepositoryName` (optional): Repository name. Default: "PowerToys"
+
+**Usage:**
+```powershell
+.\Get-PrIncrementalChanges.ps1 -PullRequestNumber 42374 -LastReviewedCommitSha "abc123def456"
+```
+
+**Output:** JSON object with detailed change analysis:
+```json
+{
+  "PullRequestNumber": 42374,
+  "CurrentHeadSha": "xyz789abc123",
+  "LastReviewedSha": "abc123def456",
+  "IsIncremental": true,
+  "NeedFullReview": false,
+  "ChangedFiles": [
+    {
+      "Filename": "src/modules/cmdpal/main.cpp",
+      "Status": "modified",
+      "Additions": 15,
+      "Deletions": 8,
+      "Changes": 23
+    }
+  ],
+  "NewCommits": [
+    {
+      "Sha": "def456",
+      "Message": "Fix memory leak",
+      "Author": "John Doe",
+      "Date": "2025-11-07T10:30:00Z"
+    }
+  ],
+  "Summary": "Incremental review: 1 new commit(s), 1 file(s) changed since SHA abc123d"
+}
+```
+
+**Scenarios Handled:**
+- **No LastReviewedCommitSha**: Returns `NeedFullReview: true` (first review)
+- **SHA matches current HEAD**: Returns empty `ChangedFiles` (no changes)
+- **Force-push detected**: Returns `NeedFullReview: true` (SHA not in history)
+- **Incremental changes**: Returns list of changed files and new commits
+
+### Test-IncrementalReview.ps1
+
+Helper script to test and preview incremental review detection before running the full review.
+
+**Purpose:** Validate incremental review functionality and preview what changed.
+
+**Parameters:**
+- `PullRequestNumber` (required): Pull request number
+- `RepositoryOwner` (optional): Repository owner. Default: "microsoft"
+- `RepositoryName` (optional): Repository name. Default: "PowerToys"
+
+**Usage:**
+```powershell
+.\Test-IncrementalReview.ps1 -PullRequestNumber 42374
+```
+
+**Output:** Colored console output showing:
+- Current and last reviewed SHAs
+- Whether incremental review is possible
+- List of new commits and changed files
+- Recommended review strategy
+
+## Workflow Integration
+
+These scripts integrate with the PR review prompt (`.github/prompts/review-pr.prompt.md`).
+
+### Typical Review Flow
+
+1. **Initial Review (Iteration 1)**
+   - Review prompt processes the PR
+   - Creates `Generated Files/prReview/{PR}/00-OVERVIEW.md`
+   - Includes review metadata section with current HEAD SHA
+
+2. **Subsequent Reviews (Iteration 2+)**
+   - Review prompt reads `00-OVERVIEW.md` to get last reviewed SHA
+   - Calls `Get-PrIncrementalChanges.ps1` to detect what changed
+   - If incremental:
+     - Reviews only changed files
+     - Skips irrelevant review steps (e.g., skip Localization if no `.resx` files changed)
+   - Uses `Get-GitHubPrFilePatch.ps1` to get patches for changed files
+   - Updates `00-OVERVIEW.md` with new SHA and iteration number
+
+### Manual Testing Workflow
+
+Preview changes before review:
+```powershell
+# Check what changed in PR #42374 since last review
+.\Test-IncrementalReview.ps1 -PullRequestNumber 42374
+
+# Get incremental changes programmatically
+$changes = .\Get-PrIncrementalChanges.ps1 -PullRequestNumber 42374 -LastReviewedCommitSha "abc123" | ConvertFrom-Json
+
+if (-not $changes.NeedFullReview) {
+    Write-Host "Only need to review $($changes.ChangedFiles.Count) files"
+    
+    # Review each changed file
+    foreach ($file in $changes.ChangedFiles) {
+        Write-Host "Reviewing $($file.Filename)..."
+        .\Get-GitHubPrFilePatch.ps1 -PullRequestNumber 42374 -FilePath $file.Filename
+    }
+}
+```
+
+## Error Handling and Troubleshooting
+
+### Common Requirements
+
+All scripts:
+- Exit with code 1 on error
+- Write detailed error messages to stderr
+- Require `gh` CLI to be installed and authenticated
+
+### Common Issues
+
+**Error: "gh not found"**
+- **Solution**: Install GitHub CLI from https://cli.github.com/ and run `gh auth login`
+
+**Error: "Failed to query GitHub API"**
+- **Solution**: Verify `gh` authentication with `gh auth status`
+- **Solution**: Check PR number exists and you have repository access
+
+**Error: "PR not found"**
+- **Solution**: Verify the PR number is correct and still exists
+- **Solution**: Ensure repository owner and name are correct
+
+**Error: "SHA not found" or "Force-push detected"**
+- **Explanation**: Last reviewed SHA no longer exists in branch history (force-push occurred)
+- **Solution**: A full review is required; incremental review not possible
+
+**Tests show "FAIL" but functionality works**
+- **Explanation**: Some tests may show exit code failures even when logic is correct
+- **Solution**: Check test output message - if it says "Correctly detected", functionality is working
+
+**Error: "Could not find insertion point"**
+- **Explanation**: Overview file doesn't have expected "**Changed files:**" line
+- **Solution**: Verify overview file format is correct or regenerate it
+
+### Verification Checklist
+
+After setup, verify:
+- [ ] `Run-ReviewToolsTests.ps1` shows 9+ tests passing
+- [ ] `Get-PrIncrementalChanges.ps1` returns valid JSON
+- [ ] `Test-IncrementalReview.ps1` analyzes a PR without errors
+- [ ] `Get-GitHubRawFile.ps1` downloads files correctly
+- [ ] `Get-GitHubPrFilePatch.ps1` retrieves patches correctly
+
+## Best Practices
+
+### For Review Authors
+
+1. **Test before full review**: Use `Test-IncrementalReview.ps1` to preview changes 
+2. **Check for force-push**: Review the analysis output - force-pushes require full reviews
+3. **Smart step filtering**: Skip review steps for file types that didn't change
+
+### For Script Users
+
+1. **Use absolute paths**: When specifying folders, use absolute paths to avoid ambiguity
+2. **Check exit codes**: Scripts exit with code 1 on error - check `$LASTEXITCODE` in automation
+3. **Parse JSON output**: Use `ConvertFrom-Json` to work with structured output from `Get-PrIncrementalChanges.ps1`
+4. **Handle empty results**: Check `ChangedFiles.Count` before iterating
+
+### Performance Tips
+
+1. **Batch operations**: When reviewing multiple PRs, collect all PR numbers and process in batch
+2. **Cache raw files**: Download baseline files once and reuse for multiple comparisons
+3. **Filter early**: Use incremental detection to skip unnecessary file reviews
+4. **Parallel processing**: Consider processing independent PRs in parallel
+
+## Integration with AI Review Systems
+
+These tools are designed to work with AI-powered review systems:
+
+1. **Copilot Instructions**: This file serves as reference documentation for GitHub Copilot
+2. **Structured Output**: JSON output from scripts is easily parsed by AI systems
+3. **Incremental Intelligence**: AI can focus on changed files for more efficient reviews
+4. **Metadata Tracking**: Review iterations are tracked for context-aware suggestions
+
+### Example AI Integration
+
+```powershell
+# Get incremental changes
+$analysis = .\Get-PrIncrementalChanges.ps1 -PullRequestNumber $PR | ConvertFrom-Json
+
+# Feed to AI review system
+$reviewPrompt = @"
+Review the following changed files in PR #$PR:
+$($analysis.ChangedFiles | ForEach-Object { "- $($_.Filename) ($($_.Status))" } | Out-String)
+
+Focus on incremental changes only. Previous review was at SHA $($analysis.LastReviewedSha).
+"@
+
+# Execute AI review with context
+Invoke-AIReview -Prompt $reviewPrompt -Files $analysis.ChangedFiles
+```
+
+## Support and Further Information
+
+For detailed script documentation, use PowerShell's help system:
+```powershell
+Get-Help .\Get-PrIncrementalChanges.ps1 -Full
+Get-Help .\Test-IncrementalReview.ps1 -Detailed
+```
+
+Related documentation:
+- `.github/prompts/review-pr.prompt.md` - Complete review workflow guide
+- `doc/devdocs/` - PowerToys development documentation
+- GitHub CLI documentation: https://cli.github.com/manual/
+
+For issues or questions, refer to the PowerToys contribution guidelines.