pr-review

name	pr-review
description	End-to-end PR reviewer for dotnet/maui. Orchestrates 3 phases — Pre-Flight, Try-Fix, Report. Gate runs separately before this skill. Use when asked to 'review PR #XXXXX', 'work on PR #XXXXX', or 'fix issue #XXXXX'.

PR Review — 3-Phase Orchestrator

End-to-end PR review workflow that orchestrates phases to explore independent fix alternatives and produce a recommendation.

Trigger phrases: "review PR #XXXXX", "work on PR #XXXXX", "fix issue #XXXXX"

🚨 NEVER use gh pr review --approve or --request-changes. AI agents must NEVER post review comments. 🚨 DO NOT post any comments to the PR. This skill only produces output files in CustomAgentLogsTmp/PRState/.

---

Overview

Gate (pre-run)    → Already completed by Review-PR.ps1 before this skill runs
Phase 1: Pre-Flight   → Gather context, classify files, code review     → .github/pr-review/pr-preflight.md
Phase 2: Try-Fix      → ⚠️ MANDATORY multi-model exploration           → invoke try-fix skill (×4 models)
Phase 3: Report       → Write review recommendation                     → .github/pr-review/pr-report.md

Gate and Branch setup are handled by Review-PR.ps1 before this skill is invoked. The gate result is passed in the prompt. Do NOT re-run gate verification.

All phases write output to: CustomAgentLogsTmp/PRState/{PRNumber}/PRAgent/{phase}/content.md Pre-Flight also writes: CustomAgentLogsTmp/PRState/{PRNumber}/PRAgent/pre-flight/code-review.md

---

Critical Rules

• ❌ Never run git checkout or git switch to change branches — stay on the review branch set up by the caller
• ❌ Never stop and ask the user — use best judgment to skip blocked phases and continue
• ❌ Never mark a phase complete with pending fields
• ❌ Never skip Phase 2 multi-model exploration — it is MANDATORY for every review, no exceptions
• ❌ Never run git commands that change branch state during Phases 2-3 (scripts handle file manipulation)
• ❌ Never duplicate phase content — each phase writes ONLY to its own content.md. Do NOT copy gate results into try-fix or report content files.
• ✅ Always create CustomAgentLogsTmp/ output files for every phase
• ✅ Always include Co-authored-by: Copilot <[e-mail]> in any commits
• ✅ Always use skills' scripts — don't bypass with manual commands
• ✅ Each phase's content.md must use the exact template from the phase instruction doc — no extra prose

Multi-Model Configuration

Phase 2 uses these 4 AI models (run SEQUENTIALLY — they modify the same files):

Order	Model
1	claude-opus-4.6
2	claude-opus-4.7
3	gpt-5.3-codex
4	gpt-5.5

🚨 MANDATORY: Use mode: "sync" for ALL try-fix task invocations. Never use mode: "background". Background mode causes the orchestrator to move on before the attempt finishes, which means try-fix/content.md is never written and try-fix results are lost from the PR comment. Each try-fix task MUST complete and return its result before you proceed to the next attempt or to the Phase 3 completion checklist.

Environment Blockers

Blocker Type	Max Retries	Then Do
Missing tool/driver	1 install attempt	Skip phase, continue
Server errors (500, timeout)	1 retry	Skip phase, continue
Port conflicts	1 (kill process)	Skip phase, continue
Build failures in try-fix	2 attempts	Skip remaining models, proceed to Report
Configuration issues	1 fix attempt	Skip phase, continue

---

Phase 1: Pre-Flight

Read and follow .github/pr-review/pr-preflight.md

Gather context from the issue, PR, comments, classify changed files, and perform a deep code review using the code-review skill.

Pre-Flight now has two parts:

• Part A (Steps 1–6): Context gathering — read issue, PR, comments, classify files
• Part B (Step 7): Code review — independence-first code analysis using .github/skills/code-review/SKILL.md and .github/skills/code-review/references/review-rules.md

Outputs:

• pre-flight/content.md — Context + code review summary
• pre-flight/code-review.md — Full code-review output (findings, blast radius, failure-mode probes, verdict)

Gate: None — always runs.

Why code review runs here: The code-review findings (❌ Errors, ⚠️ Warnings, failure-mode probes, blast radius) become structured hints for Phase 2 (Try-Fix). Instead of each model starting from scratch, they receive concrete code concerns to address, leading to higher-quality fix exploration.

---

Phase 2: Try-Fix → Invoke try-fix Skill (×4 Models)

Read and follow .github/skills/try-fix/SKILL.md

⚠️ THIS PHASE IS MANDATORY. YOU MUST NEVER SKIP IT. NO EXCEPTIONS.

Even if the PR's fix looks correct and Gate passed, you MUST still run all 4 models to explore alternative approaches. The purpose is to find the BEST fix, not just validate one.

🚨 CRITICAL: try-fix is Independent of PR's Fix

"Independent" means each model explores a different fix approach from the PR's fix — not that models are isolated from code-review context. Code-review findings are provided as advisory background to improve fix quality.

The purpose is NOT to re-test the PR's fix, but to:

1. Generate independent fix ideas — What would YOU do to fix this bug?
2. Test those ideas empirically — Actually implement and run tests
3. Compare with PR's fix — Is there a simpler/better alternative?
4. Learn from failures — Record WHY failed attempts didn't work

Checklist (you MUST complete ALL of these)

• Attempt 1 launched with claude-opus-4.6
• try-fix/content.md updated with attempt 1 result
• Attempt 2 launched with claude-opus-4.7
• try-fix/content.md updated with attempt 2 result
• Attempt 3 launched with gpt-5.3-codex
• try-fix/content.md updated with attempt 3 result
• Attempt 4 launched with gpt-5.5
• try-fix/content.md updated with attempt 4 result
• Cross-pollination round completed (all models queried)
• Best fix selected with comparison table

Round 1: Independent Exploration

For each model, invoke try-fix skill via a general-purpose task agent with that model:

prompt: |
  Invoke the try-fix skill for PR #XXXXX:
  - problem: {bug description from Pre-Flight}
  - platform: {platform from Platform Selection}
  - test_command: {test command from detected test type — use BuildAndRunHostApp.ps1 for UITest, Run-DeviceTests.ps1 for DeviceTest, dotnet test for UnitTest}
  - target_files:
    - src/{area}/{file1}.cs
    - src/{area}/{file2}.cs
  - hints: |
      Code review found the following concerns (advisory — use to inform your approach, not as a checklist):
      Errors:
        - {❌ Error finding 1 with file:line reference}
      # Include warnings ONLY if relevant to the root cause:
      # Warnings:
      #   - {⚠️ Warning — omit if unrelated to root cause}
      Failure modes:
        - {Failure mode 1}: {What happens in this scenario}
      Blast radius: {Summary — e.g., "Runs for ALL toolbar items at startup, not just badged ones"}
      Code review verdict: {LGTM / NEEDS_CHANGES / NEEDS_DISCUSSION} (confidence: {high/medium/low})

  Generate ONE independent fix idea. Review the PR's fix first to ensure your approach is DIFFERENT.
  "Independent" means exploring a different fix approach — the code review context above is background
  information to help you make better decisions, not a constraint on your exploration.

Include code review context in the hints field (try-fix's documented optional input). If Pre-Flight code review found no issues, use hints: "Code review found no issues (verdict: LGTM)". If code review was SKIPPED, omit the hints field entirely.

Selectivity: Only include ❌ Error findings and failure-mode probes that are relevant to the bug being fixed. Omit 💡 Suggestions. Include ⚠️ Warnings only if directly related to the root cause.

Wait for each to complete before starting the next.

🧹 MANDATORY: Clean up between attempts:

# Restore baseline from previous attempt — this is the ONLY way to restore.
# Do NOT use manual git checkout/restore/reset commands.
pwsh .github/scripts/EstablishBrokenBaseline.ps1 -Restore

📝 MANDATORY: Update try-fix/content.md after EVERY attempt. Do not wait until all attempts are done. After each try-fix attempt completes (pass or fail), immediately write/update CustomAgentLogsTmp/PRState/{PRNumber}/PRAgent/try-fix/content.md with all results so far. This ensures the PR comment always reflects the latest try-fix state, even if a later attempt times out or the agent is interrupted.

Round 2+: Cross-Pollination (MANDATORY)

After Round 1, invoke EACH model via task agent:

"Review PR #XXXXX fix attempts:
  - Attempt 1: {approach} - ✅/❌
  - Attempt 2: {approach} - ✅/❌
  ...
  Do you have any NEW fix ideas? Reply: 'NEW IDEA: {desc}' or 'NO NEW IDEAS'"

Run any new ideas as additional try-fix attempts. Repeat until all say "NO NEW IDEAS" (max 3 rounds).

Selecting the Best Fix

Compare all passing candidates on:

1. Must pass tests — Only consider ✅ PASS candidates
2. Simplest solution — Fewer files, fewer lines
3. Most robust — Handles edge cases
4. Matches codebase style — Consistent with existing patterns

Output File

mkdir -p CustomAgentLogsTmp/PRState/{PRNumber}/PRAgent/try-fix

Write content.md:

### Fix Candidates
| # | Source | Approach | Test Result | Files Changed | Notes |
|---|--------|----------|-------------|---------------|-------|
| 1 | try-fix | {approach} | ✅/❌ | 1 file | {insight} |
| ... | ... | ... | ... | ... | ... |
| PR | PR #XXXXX | {approach} | ✅ PASSED (Gate) | 2 files | Original PR |

### Cross-Pollination
| Model | Round | New Ideas? | Details |
|-------|-------|------------|---------|
| ... | 2 | Yes/No | {idea or "NO NEW IDEAS"} |

**Exhausted:** {Yes/No}
**Selected Fix:** {PR's fix / Candidate #N} — {Reason}

Common Mistakes

• ❌ Looking at PR's fix before generating ideas — generate independently first
• ❌ Running try-fix in parallel — SEQUENTIAL ONLY, always mode: "sync"
• ❌ Using mode: "background" for try-fix tasks — results will be lost
• ❌ Skipping cleanup between attempts — ALWAYS run cleanup commands
• ❌ Declaring exhaustion without querying all 4 models

---

Phase 3: Report

Read and follow .github/pr-review/pr-report.md

Deliver the final review recommendation.

🚨 DO NOT post any comments. All output goes to CustomAgentLogsTmp/PRState/.

Gate: Phases 1-2 must be complete.

---

Output Directory Structure (MANDATORY)

CustomAgentLogsTmp/PRState/{PRNumber}/PRAgent/
├── pre-flight/
│   ├── content.md              # Phase 1 output (context + code review summary)
│   └── code-review.md          # Full code-review skill output (findings, blast radius, verdict)
├── gate/
│   └── content.md              # Gate output (pr-gate, run separately)
├── try-fix/
│   ├── content.md              # Phase 2 summary
│   └── attempt-{N}/            # Per-model attempt
│       ├── baseline.log         # Baseline establishment proof
│       ├── approach.md          # What was tried
│       ├── result.txt           # Pass / Fail / Blocked
│       ├── fix.diff             # git diff of changes
│       ├── test-output.log      # Full test command output
│       ├── reviewer-findings.json  # Inline expert self-review (`[]` if clean) — reflects the FINAL diff (refreshed by Step 7.5 if test loop modified code)
│       ├── reviewer-findings.diff  # Snapshot of the diff that the self-review evaluated (used by Step 7.5 to detect drift)
│       └── analysis.md          # Why it worked/failed + self-review summary
└── report/
    └── content.md              # Phase 3 output (pr-report)

---

Quick Reference

Phase	Instructions	Key Action	If Blocked
Gate (pre-run)	pr-gate.md	Verify tests (run by Review-PR.ps1)	Result passed in prompt — if missing, document and continue
1. Pre-Flight	pr-preflight.md	Read issue + PR context + code review	Skip missing info; if code review fails, set verdict to SKIPPED
2. Try-Fix	try-fix skill (×4)	4-model exploration with code-review hints (MANDATORY)	Skip failing models, continue
3. Report	pr-report.md	Write review recommendation	Never skip

---

Common Errors and Recovery

Error	Cause	Fix
ENOENT: no such file on skill	Dirty working tree from prior attempt	Run cleanup: -Restore + git checkout HEAD -- . + git clean -fd --exclude=CustomAgentLogsTmp/
Dirty working tree before attempt	Prior attempt didn't restore	Same cleanup as above
Build errors in unmodified files	Stale state	Cleanup + retry; if still fails, treat as environment blocker