PR Agent

PR Agent

The PR Agent is a unified 5-phase workflow for investigating GitHub issues and reviewing/working on pull requests. It handles everything from context gathering through test verification, fix exploration, and creating PRs or review reports.

Quick Start

Using GitHub Copilot CLI

# Start GitHub Copilot CLI
copilot

# Invoke the PR agent
/agent pr

# Then ask it to work on an issue or PR
please fix issue #12345
please review PR #67890

Trigger Phrases

Phrase	Description
"Fix issue #XXXXX"	Works whether or not a PR exists
"Work on issue #XXXXX"	Investigate and implement a fix
"Review PR #XXXXX"	Review an existing PR with independent analysis
"Continue working on #XXXXX"	Resume from where you left off

The 5-Phase Workflow

┌─────────────────────────────────────────┐     ┌─────────────────────────────────────────────┐
│  Phases 1-3 (pr.md)                     │     │  Phases 4-5 (post-gate.md)                  │
│                                         │     │                                             │
│  1. Pre-Flight  →  2. Tests  →  3. Gate │ ──► │  4. Fix  →  5. Report                       │
│                          ⛔              │     │                                             │
│                     MUST PASS            │     │  (Only after Gate ✅ PASSED)                │
└─────────────────────────────────────────┘     └─────────────────────────────────────────────┘

Phase 1: Pre-Flight

Context gathering only - no code analysis, no fix opinions, no running tests.

• Create state file in .github/agent-pr-session/pr-XXXXX.md
• Read issue description and comments
• Document platforms affected
• Identify files changed (if PR exists)
• Note disagreements and edge cases from comments

Phase 2: Tests

Ensure reproduction tests exist - tests must be verified to FAIL.

• Check if tests already exist in PR
• If not, create them using the write-tests skill
• Verify tests compile
• Verify tests FAIL (reproduce the bug)

Phase 3: Gate ⛔

Mandatory checkpoint - must pass before continuing.

• For PRs: Verify tests FAIL without fix, PASS with fix
• For Issues: Confirm tests were verified to fail in Phase 2
• Uses verify-tests-fail-without-fix skill

If Gate fails, stop and fix the tests before proceeding.

Phase 4: Fix

Explore independent alternatives using the try-fix skill.

Even when a PR already has a fix, Phase 4 requires running try-fix to:

1. Generate independent fix ideas (without looking at PR's solution)
2. Test alternatives empirically
3. Compare with PR's fix

The PR's fix is already validated by Gate. The try-fix skill explores if there's something better.

Phase 5: Report

Deliver the result:

• For PRs: Write review with APPROVE or REQUEST CHANGES
• For Issues: Create a new PR with the fix

Skills Used

Skill	Purpose
write-tests	Creates UI tests for issues following MAUI conventions
verify-tests-fail-without-fix	Verifies tests catch bugs (auto-detects mode)
try-fix	Proposes and tests independent fix approaches
pr-build-status	Retrieves Azure DevOps build status for PRs

State Tracking

The agent maintains state in .github/agent-pr-session/pr-XXXXX.md files. This allows:

• Resuming interrupted sessions
• Tracking progress across phases
• Recording fix attempts and their outcomes

When NOT to Use

Task	Use Instead
Just run tests manually	sandbox-agent
Only write tests without fixing	uitest-coding-agent
Quick manual validation	sandbox-agent

File Locations

File	Purpose
.github/agents/pr.md	Phases 1-3 (Pre-Flight, Tests, Gate)
.github/agents/pr/post-gate.md	Phases 4-5 (Fix, Report)
.github/skills/try-fix/SKILL.md	Fix exploration skill
.github/skills/write-tests/SKILL.md	Test creation skill
.github/skills/verify-tests-fail-without-fix/SKILL.md	Test verification skill

Related Documentation

• UI Testing Guide - How to write UI tests
• Contributing Guidelines
• Development Guide

---

Last Updated: January 2026