Enhance PR agent: multi-model workflow, blocker handling, shared rules extraction (dotnet#33813)

<!-- Please let the below note in for people that find this PR -->
> [!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](https://github.com/dotnet/maui/wiki/Testing-PR-Builds) from
this PR and let us know in a comment if this change resolves your issue.
Thank you!

## Summary

This PR significantly enhances the PR agent workflow with improvements
across **two development phases**:

### Phase 1: Original Enhancements (Commits 1-8)
1. **Multi-model try-fix exploration** - Uses 5 different AI models to
explore alternative solutions
2. **Environment blocker handling** - Strict rules to stop and ask user
when environment issues occur
3. **Review automation script** - PowerShell script that invokes Copilot
CLI directly for PR reviews
4. **Branch safety rules** - Prevents agent from switching branches
during reviews
5. **Template formatting rules** - Exact template adherence for
downstream script compatibility

### Phase 2: Consolidation & Simplification (Commit 9)
After multi-model review (5 models: Claude Sonnet 4.5, Claude Opus 4.5,
GPT-5.2, GPT-5.2-Codex, Gemini 3 Pro), the following improvements were
made:

6. **Shared rules extraction** - Created `SHARED-RULES.md` to eliminate
duplication across files
7. **Simplified git policy** - Agent never runs git commands; always
assumes correct branch
8. **State file handling** - Changed "commit" to "save" (state files are
gitignored)
9. **Reduced verbosity** - Compressed cross-pollination section,
converted PLAN-TEMPLATE to checklist

---

## Commits

### 1. `80d7e412c2` - Update pr agent with multi-model try-fix workflow

**Why:** The original PR agent only used a single model for exploring
fixes. Different AI models have different strengths and may find
solutions others miss.

**Changes:**
- Added Phase 4 multi-model workflow using 5 models:
- `claude-sonnet-4.5`, `claude-opus-4.5`, `gpt-5.2`, `gpt-5.2-codex`,
`gemini-3-pro-preview`
- Cross-pollination loop: Share results between models to spark new
ideas
- Continue until all models confirm "no more approaches to explore"

---

### 2. `69cc6af403` - Address Copilot review suggestions

**Why:** Initial PR review feedback suggested improvements.

**Changes:**
- Minor formatting and clarity improvements to pr.md

---

### 3. `fe55c3fd21` - Add rules for template formatting and skill script
usage

**Why:** Downstream scripts depend on exact regex patterns in state
files. Agents were "improving" templates by adding attributes like
`open` which broke parsing.

**Changes:**
- Added "Follow Templates EXACTLY" rule - no adding attributes, no
improving formats
- Added "Use Skills' Scripts" rule - run provided PowerShell scripts,
don't bypass with manual commands

---

### 4. `debbee608e` - Add 'Stop on Environment Blockers' rule to PR
agent

**Why:** Agent was continuing through phases when environment issues
(missing Appium, WinAppDriver errors) prevented completion, leading to
incomplete reviews.

**Changes:**
- Added explicit blocker handling section to pr.md
- Common blockers: Appium drivers, WinAppDriver, Xcode, emulators, port
conflicts
- Must STOP, report the blocker, and ask user how to proceed
- Never mark phase as blocked and continue to next phase

---

### 5. `ad29f6a796` - Add PR review plan template and Review-PR.ps1
script

**Why:** Need a reusable template for consistent PR reviews and a script
to automate invocation.

**Changes:**
- Created `.github/agents/pr/PLAN-TEMPLATE.md` - Reusable 5-phase review
plan
- Created `.github/scripts/Review-PR.ps1` - Script to prepare
environment and invoke Copilot CLI

---

### 6. `886ea2aa8e` - Improve blocker handling and fix Review-PR.ps1 for
Copilot CLI

**Why:** During PR dotnet#27300 review, agent spent 10+ tool calls
troubleshooting WinAppDriver instead of stopping after first failure.

**Changes:**
- Added strict retry limits table:
  | Blocker Type | Max Retries | Action |
  |--------------|-------------|--------|
  | Server errors (500, timeout) | 0 | STOP immediately |
  | Missing tools | 1 install | STOP and ask |
  | Port conflicts | 1 kill | STOP and ask |
  | WinAppDriver errors | 0 | STOP immediately |
- Added "What I tried" section to blocker report template
- New prohibitions: Never spend more than 2-3 tool calls on same blocker

---

### 7. `d67da75e85` - Update Review-PR.ps1 to invoke Copilot CLI
directly

**Why:** Initially thought Copilot CLI was interactive-only. Discovered
it supports `-i <prompt>` and `-p <prompt>` for programmatic invocation.

**Changes:**
- Script now invokes `copilot --agent pr -i "<prompt>"` directly
- Validates both `gh` CLI and `copilot` CLI are installed
- New `-NoInteractive` switch for `-p` mode (exits after completion)
- Dry run mode shows exactly what would be invoked

---

### 8. `ed74c574a5` - Add 'Do NOT Switch Branches' rule to pr agent

**Why:** During PR review testing, the pr agent ran `git checkout`, `git
stash`, and other branch-switching commands, causing loss of local
changes and confusion about which code was being reviewed.

**Changes:**
- Added explicit "Do NOT Switch Branches" rule to both pr.md and
PLAN-TEMPLATE.md
- Forbidden commands: `git checkout`, `git switch`, `gh pr checkout`,
`git stash`
- Agent must work on current branch as-is, using `git diff` or `gh pr
diff` to see PR changes
- Fixed variable expansion in Review-PR.ps1 prompt (double backticks for
here-strings)

---

### 9. `632bfb7155` - Extract shared rules, simplify git policy, reduce
duplication

**Why:** Multi-model review (5 AI models) identified significant
duplication (~200 lines) across files, conflicting "commit" terminology,
and overly verbose sections. The git checkout prohibition also
conflicted with workflow steps that mentioned git checkout.

**Changes:**
- **Created `SHARED-RULES.md`** (167 lines) - Single source of truth
for:
  - Phase Completion Protocol
  - Follow Templates EXACTLY
  - No Direct Git Commands (absolute - agent never runs git)
  - Use Skills' Scripts
  - Stop on Environment Blockers (with retry limits)
  - Multi-Model Configuration (5 models list)
  - Platform Selection guidance
  
- **Simplified git policy** - Agent is ALWAYS on correct branch, never
runs git commands:
  - Removed git fetch/checkout from Phase 1 Pre-Flight
  - Phase 5: User handles commit/push/PR creation
- Changed all "State file committed" → "State file saved" (gitignored
files)
  
- **Compressed content**:
  - Cross-pollination ASCII box: 51 → 20 lines
  - PLAN-TEMPLATE.md: Full docs → Pure checklist (226 → 112 lines)
  - pr.md: 662 → 535 lines (-19%)
  - post-gate.md: 403 → 302 lines (-25%)
  - Total reduction: 1291 → 1116 lines (-14%)

- **Eliminated duplication**:
  - Blocker handling was in 3 files → now in SHARED-RULES.md only
- Phase Completion Protocol was in 2 files → now in SHARED-RULES.md only
  - Model list was in 3 files → now in SHARED-RULES.md only

---

## Files Changed

| File | Purpose |
|------|---------|
| `.github/agents/pr.md` | Main PR agent instructions (Phases 1-3) |
| `.github/agents/pr/post-gate.md` | Phase 4-5 instructions (multi-model
try-fix) |
| `.github/agents/pr/PLAN-TEMPLATE.md` | **NEW** - Reusable 5-phase
review checklist |
| `.github/agents/pr/SHARED-RULES.md` | **NEW** - Extracted shared rules
(single source of truth) |
| `.github/scripts/Review-PR.ps1` | **NEW** - Script to invoke Copilot
CLI for PR review |

---

## Usage

```powershell
# Interactive mode (default) - stays open for follow-up
pwsh .github/scripts/Review-PR.ps1 -PRNumber 33687

# Non-interactive mode - exits when done
pwsh .github/scripts/Review-PR.ps1 -PRNumber 33687 -NoInteractive

# Specific platform
pwsh .github/scripts/Review-PR.ps1 -PRNumber 33687 -Platform ios

# Skip merge if already on branch
pwsh .github/scripts/Review-PR.ps1 -PRNumber 33687 -SkipMerge

# Dry run to preview
pwsh .github/scripts/Review-PR.ps1 -PRNumber 33687 -DryRun
```

---

## Multi-Model Validation

The final changes (commit 9) were validated by 5 AI models:

| Model | Verdict | Key Feedback |
|-------|---------|--------------|
| Claude Sonnet 4.5 | ✅ READY TO MERGE | "All git command instructions
successfully removed" |
| Claude Opus 4.5 | ✅ READY TO MERGE | "Excellent refactoring, no
conflicting guidance" |
| GPT-5.2 | ✅ READY TO MERGE | "Progressive disclosure maintained" |
| GPT-5.2-Codex | ✅ READY TO MERGE | "No instructions to run git
commands remain" |
| Gemini 3 Pro | ✅ READY TO MERGE | "Agent is instructed to STOP and ask
user for commits" |

---

## Testing

Tested by reviewing PR dotnet#27300 (ScrollView ScrollToAsync fix):
- Pre-Flight phase completed successfully
- Tests phase verified test files exist
- Gate phase encountered WinAppDriver blocker → agent correctly stopped
and asked
- Blocker handling rules validated through real-world usage
- **Branch safety verified**: Agent stayed on branch instead of
switching

---------

Co-authored-by: Jakub Florkowski <kubaflo123@gmail.com>

Author: PureWeen

.github/agents/pr.md

@@ -41,31 +41,23 @@ After Gate passes, read `.github/agents/pr/post-gate.md` for **Phases 4-5**.
 
 ---
 
-## Phase Completion Protocol (CRITICAL)
+## 🚨 Critical Rules
 
-**Before changing ANY phase status to ✅ COMPLETE:**
+**Read `.github/agents/pr/SHARED-RULES.md` for complete details on:**
+- Phase Completion Protocol (fill ALL pending fields before marking complete)
+- Follow Templates EXACTLY (no `open` attributes, no "improvements")
+- No Direct Git Commands (use `gh pr diff/view`, let scripts handle files)
+- Use Skills' Scripts (don't bypass with manual commands)
+- Stop on Environment Blockers (strict retry limits, report and ask user)
+- Multi-Model Configuration (5 models for Phase 4)
+- Platform Selection (must be affected AND available on host)
 
-1. **Read the state file section** for the phase you're completing
-2. **Find ALL ⏳ PENDING and [PENDING] fields** in that section
-3. **Fill in every field** with actual content
-4. **Verify no pending markers remain** in your section
-5. **Commit the state file** with complete content
-6. **Then change status** to ✅ COMPLETE
+**Key points:**
+- ❌ Never run `git checkout`, `git switch`, `git stash`, `git reset` - agent is always on correct branch
+- ❌ Never continue after environment blocker - STOP and ask user
+- ❌ Never mark phase ✅ with [PENDING] fields remaining
 
-**Rule:** Status ✅ means "documentation complete", not "I finished thinking about it"
-
----
-
-### 🚨 CRITICAL: Phase 4 Always Uses `try-fix` Skill
-
-**Even when a PR already has a fix**, Phase 4 requires running the `try-fix` skill to:
-1. **Independently explore alternative solutions** - Generate fix ideas WITHOUT looking at the PR's solution
-2. **Test alternatives empirically** - Actually implement and run tests, don't just theorize
-3. **Compare with PR's fix** - PR's fix is already validated by Gate; try-fix explores if there's something better
-
-The PR's fix is NOT tested by try-fix (Gate already did that). try-fix generates and tests YOUR independent ideas.
-
-This ensures independent analysis rather than rubber-stamping the PR.
+Phase 4 uses a 5-model exploration workflow. See `post-gate.md` for detailed instructions after Gate passes.
 
 ---
 
@@ -233,7 +225,7 @@ This file:
 - Serves as your TODO list for all phases
 - Tracks progress if interrupted
 - Must exist before you start gathering context
-- **Always include when committing changes** (to `CustomAgentLogsTmp/PRState/`)
+- **Always include when saving changes** (to `CustomAgentLogsTmp/PRState/`)
 - **Phases 4-5 sections are added AFTER Gate passes** (see `pr/post-gate.md`)
 
 **Then gather context and update the file as you go.**
@@ -242,11 +234,7 @@ This file:
 
 **If starting from a PR:**
 ```bash
-# Checkout the PR
-git fetch origin pull/XXXXX/head:pr-XXXXX
-git checkout pr-XXXXX
-
-# Fetch PR metadata
+# Fetch PR metadata (agent is already on correct branch)
 gh pr view XXXXX --json title,body,url,author,labels,files
 
 # Find and read linked issue
@@ -256,7 +244,6 @@ gh issue view ISSUE_NUMBER --json title,body,comments
 
 **If starting from an Issue (no PR exists):**
 ```bash
-# Stay on current branch - do NOT checkout anything
 # Fetch issue details directly
 gh issue view XXXXX --json title,body,comments,labels
 ```
@@ -351,7 +338,7 @@ The test result will be updated to `✅ PASS (Gate)` after Gate passes.
 - [ ] Files Changed table populated (if PR exists)
 - [ ] PR Discussion Summary documented (if PR exists)
 - [ ] All [PENDING] placeholders replaced
-- [ ] State file committed
+- [ ] State file saved
 
 ---
 
@@ -418,7 +405,7 @@ The script auto-detects mode based on git diff. If only test files changed, it v
 - [ ] Test file paths documented
 - [ ] "Tests verified to FAIL" note added
 - [ ] Test category identified
-- [ ] State file committed
+- [ ] State file saved
 
 ---
 
@@ -441,13 +428,42 @@ Tests were already verified to FAIL in Phase 2. Gate is a confirmation step:
 **If starting from a PR (fix exists):**
 Use full verification mode - tests should FAIL without fix, PASS with fix.
 
+### Platform Selection for Gate
+
+**🚨 CRITICAL: Choose a platform that is BOTH affected by the bug AND available on the current host.**
+
+**Step 1: Identify affected platforms** from Pre-Flight:
+- Check the "Platforms Affected" checkboxes in the state file
+- Check issue labels (e.g., `platform/iOS`, `platform/Android`)
+- Check which platform-specific files the PR modifies
+
+**Step 2: Match to available platforms on current host:**
+
+| Host OS | Available Platforms |
+|---------|---------------------|
+| Windows | Android, Windows |
+| macOS | Android, iOS, MacCatalyst |
+
+**Step 3: Select the best match:**
+1. Pick a platform that IS affected by the bug
+2. That IS available on the current host
+3. Prefer the platform most directly impacted by the PR's code changes
+
+**Example decisions:**
+- Bug affects iOS/Windows/MacCatalyst, host is Windows → Test on **Windows**
+- Bug affects iOS only, host is Windows → **STOP** - cannot test (ask user)
+- Bug affects Android only → Test on **Android** (works on any host)
+- Bug affects all platforms → Pick based on host (Windows on Windows, iOS on macOS)
+
+**⚠️ Do NOT test on a platform that isn't affected by the bug** - the test will pass regardless of whether the fix works.
+
 **🚨 MUST invoke as a task agent** to prevent command substitution:
 
 ```markdown
 Invoke the `task` agent with agent_type: "task" and this prompt:
 
 "Invoke the verify-tests-fail-without-fix skill for this PR:
-- Platform: android (or ios)
+- Platform: [selected platform from Platform Selection above]
 - TestFilter: 'IssueXXXXX'
 - RequireFullVerification: true
 
@@ -486,7 +502,7 @@ See `.github/skills/verify-tests-fail-without-fix/SKILL.md` for full skill docum
 - [ ] Result shows PASSED ✅ or FAILED ❌
 - [ ] Test behavior documented
 - [ ] Platform tested noted
-- [ ] State file committed
+- [ ] State file saved
 
 ---
 

.github/agents/pr/PLAN-TEMPLATE.md

@@ -0,0 +1,112 @@
+# PR Review Plan Template
+
+**Reusable checklist** for the 5-phase PR Agent workflow.
+
+**Source documents:**
+- `.github/agents/pr.md` - Phases 1-3 (Pre-Flight, Tests, Gate)
+- `.github/agents/pr/post-gate.md` - Phases 4-5 (Fix, Report)
+- `.github/agents/pr/SHARED-RULES.md` - Critical rules (blockers, git, templates)
+
+---
+
+## 🚨 Critical Rules (Summary)
+
+See `SHARED-RULES.md` for complete details. Key points:
+- **Environment Blockers**: STOP immediately, report, ask user (strict retry limits)
+- **No Git Commands**: Never checkout/switch branches - agent is always on correct branch
+- **Gate via Task Agent**: Never run inline (prevents fabrication)
+- **Multi-Model try-fix**: 5 models, SEQUENTIAL only
+- **Follow Templates**: No `open` attributes, no "improvements"
+
+---
+
+## Work Plan
+
+### Phase 1: Pre-Flight
+- [ ] Create state file: `CustomAgentLogsTmp/PRState/pr-XXXXX.md`
+- [ ] Gather PR metadata (title, body, labels, author)
+- [ ] Fetch and read linked issue
+- [ ] Fetch PR comments and review feedback
+- [ ] Check for prior agent reviews (import and resume if found)
+- [ ] Document platforms affected
+- [ ] Classify changed files (fix vs test)
+- [ ] Document PR's fix approach in Fix Candidates table
+- [ ] Update state file: Pre-Flight → ✅ COMPLETE
+- [ ] Save state file
+
+**Boundaries:** No code analysis, no fix opinions, no test running
+
+### Phase 2: Tests
+- [ ] Check if PR includes UI tests
+- [ ] Verify tests follow `IssueXXXXX` naming convention
+- [ ] If tests exist: Verify they compile
+- [ ] If tests missing: Invoke `write-ui-tests` skill
+- [ ] Document test files in state file
+- [ ] Update state file: Tests → ✅ COMPLETE
+- [ ] Save state file
+
+### Phase 3: Gate ⛔
+**🚨 Cannot continue if Gate fails**
+
+- [ ] Select platform (must be affected AND available on host)
+- [ ] Invoke via **task agent** (NOT inline):
+  ```
+  "Run verify-tests-fail-without-fix skill
+   Platform: [X], TestFilter: 'IssueXXXXX', RequireFullVerification: true"
+  ```
+- [ ] ⛔ If environment blocker: STOP, report, ask user
+- [ ] Verify: Tests FAIL without fix, PASS with fix
+- [ ] If Gate fails: STOP, request test fixes
+- [ ] Update state file: Gate → ✅ PASSED
+- [ ] Save state file
+
+### Phase 4: Fix 🔧
+*(Only if Gate ✅ PASSED)*
+
+**Round 1: Run try-fix with each model (SEQUENTIAL)**
+- [ ] claude-sonnet-4.5
+- [ ] claude-opus-4.5
+- [ ] gpt-5.2
+- [ ] gpt-5.2-codex
+- [ ] gemini-3-pro-preview
+- [ ] ⛔ If blocker: STOP, report, ask user
+- [ ] Record: approach, result, files, failure analysis
+
+**Round 2+: Cross-Pollination (MANDATORY)**
+- [ ] Invoke EACH model: "Any NEW fix ideas?"
+- [ ] Record responses in Cross-Pollination table
+- [ ] Run try-fix for new ideas (SEQUENTIAL)
+- [ ] Repeat until ALL 5 say "NO NEW IDEAS" (max 3 rounds)
+
+**Completion:**
+- [ ] Cross-Pollination table has all 5 responses
+- [ ] Mark Exhausted: Yes
+- [ ] Compare passing candidates with PR's fix
+- [ ] Select best fix (results → simplicity → robustness)
+- [ ] Update state file: Fix → ✅ COMPLETE
+- [ ] Save state file
+
+### Phase 5: Report 📋
+*(Only if Phases 1-4 complete)*
+
+- [ ] Run `pr-finalize` skill
+- [ ] Generate review: root cause, candidates, recommendation
+- [ ] Post via `ai-summary-comment` skill
+- [ ] Update state file: Report → ✅ COMPLETE
+- [ ] Save final state file
+
+---
+
+## Quick Reference
+
+| Phase | Key Action | Blocker Response |
+|-------|------------|------------------|
+| Pre-Flight | Create state file | N/A |
+| Tests | Verify/create tests | N/A |
+| Gate | Task agent → verify script | ⛔ STOP, report, ask |
+| Fix | Multi-model try-fix | ⛔ STOP, report, ask |
+| Report | Post via skill | ⛔ STOP, report, ask |
+
+**State file:** `CustomAgentLogsTmp/PRState/pr-XXXXX.md`
+
+**Never:** Mark BLOCKED and continue, claim success without tests, bypass scripts