dotnet · PureWeen · Nov 23, 2025 · Nov 21, 2025 · Nov 21, 2025 · Nov 21, 2025
diff --git a/.github/README-AI.md b/.github/README-AI.md
@@ -2,14 +2,19 @@
 
 This folder contains instructions and configurations for AI coding assistants working on the .NET MAUI repository.
 
-## Quick Start: Using the PR Reviewer Agent
+## Available Agents
 
+### PR Reviewer Agent
 The PR reviewer agent conducts thorough, constructive code reviews of .NET MAUI pull requests with hands-on testing and validation.
 
-### How to Use
+### Issue Resolver Agent
+The issue resolver agent investigates, reproduces, and fixes reported issues in the .NET MAUI repository with comprehensive testing and validation.
 
-#### Option 1: GitHub Copilot CLI (Local)
+## How to Use
 
+### Option 1: GitHub Copilot CLI (Local)
+
+**PR Reviewer Agent:**
 ```bash
 # Start GitHub Copilot CLI with agent support
 copilot --allow-all-tools --allow-all-paths
@@ -18,33 +23,42 @@ copilot --allow-all-tools --allow-all-paths
 /agent pr-reviewer
 
 # Request a review
-please review <link to PR>
+please review https://github.com/dotnet/maui/pull/XXXXX
 ```
 
-#### Example
-
+**Issue Resolver Agent:**
 ```bash
+# Start GitHub Copilot CLI with agent support
 copilot --allow-all-tools --allow-all-paths
-/agent pr-reviewer
-please review https://github.com/dotnet/maui/pull/32372
+
+# Invoke the issue-resolver agent
+/agent issue-resolver
+
+# Request issue investigation
+please investigate and fix https://github.com/dotnet/maui/issues/XXXXX
 ```
 
-#### Option 2: GitHub Copilot Agents (Web)
+### Option 2: GitHub Copilot Agents (Web)
 
 1. **Navigate to the agents tab** at https://github.com/copilot/agents
 
 2. **Select your repository and branch** using the dropdown menus in the text box
 
-3. **Choose your agent** from the dropdown (pr-reviewer)
+3. **Choose your agent** from the dropdown:
+   - `pr-reviewer` for PR reviews
+   - `issue-resolver` for investigating and fixing issues
 
 4. **Enter a task** in the text box:
    - For PR reviews: `Please review this PR: https://github.com/dotnet/maui/pull/XXXXX`
+   - For issue resolution: `Please investigate and fix: https://github.com/dotnet/maui/issues/XXXXX`
 
 5. **Click Start task** or press Return
 
 6. **Follow the agent's progress** - The agent task will appear below the text box. Click into it to see live updates.
 
-## What the Agent Does
+## What the Agents Do
+
+### PR Reviewer Agent
 
 Every PR review includes:
 
@@ -55,38 +69,109 @@ Every PR review includes:
 5. **Edge Case Testing** - Tests scenarios not mentioned by the PR author
 6. **Documented Results** - Provides review with actual test data and evidence
 
-The agent will pause and ask for help if it encounters:
-- Merge conflicts when applying PR changes
+### Issue Resolver Agent
+
+Every issue resolution includes:
+
+1. **Issue Investigation** - Analyzes the reported issue and gathers context
+2. **Reproduction** - Creates minimal reproduction case in Sandbox app
+3. **Root Cause Analysis** - Identifies the underlying problem in the codebase
+4. **Fix Implementation** - Implements and tests the fix
+5. **Validation** - Tests both with and without the fix to prove it works
+6. **UI Test Creation** - Adds automated UI test to prevent regression
+7. **Documentation** - Provides detailed explanation of the issue and fix
+
+### When Agents Pause
+
+Both agents will pause and ask for help if they encounter:
+- Merge conflicts when applying changes
 - Build errors that prevent testing
 - Test results that are unexpected or confusing
 - Any step that prevents thorough validation
 
-## Important Notes
+## Agent Architecture
 
-⚠️ **We're still refining the agent instructions** to ensure it consistently follows the testing workflow.
+### Progressive Disclosure Pattern
 
-**The agent will pause and ask for help if:**
-- Merge conflicts occur when applying PR changes
-- Build errors prevent testing
-- Test results are unexpected or confusing
-- Any step fails that prevents thorough validation
+Agents use a layered approach to prevent cognitive overload:
 
-This is by design - it's better to pause and get guidance than provide incomplete or misleading reviews.
+1. **Entry Point** - Minimal instructions with mandatory pre-work
+2. **Essential Reading** - Quick-start guide with core workflow
+3. **Quick Reference** - Command templates for common tasks
+4. **Just-in-Time Learning** - Specialized guides referenced as needed
+5. **Deep Dives** - Platform-specific and error-handling details
 
-## File Structure
+**Key principle**: STOP after Essential Reading. Don't read all 11 files upfront - reference specialized guides only when needed for specific tasks.
 
-### Agent Definitions
-- **`agents/pr-reviewer.md`** - Main PR reviewer agent instructions and workflows
+### Reading Order & Stopping Points
 
-### Instruction Files
-These files provide specialized guidance for specific scenarios:
+**START HERE (required)**:
+1. Entry point (`agents/*.md`) - Understand role and mandatory pre-work
+2. Quick-start guide - Learn workflow, checkpoints, and rules
+3. **STOP** - Begin work, refer to other guides as needed
 
-- **`instructions/common-testing-patterns.md`** - Common testing patterns for command sequences (UDID extraction, builds, deploys, error checking)
+**Reference as needed**:
+- Quick-ref guide - Command templates
+- Platform guides - Platform-specific procedures
+- Error-handling - When encountering specific issues
+- Testing guidelines - For detailed testing procedures
+
+### Time Philosophy
+
+Agents work with **time budgets as estimates for planning**, not hard deadlines:
+- Budgets help recognize when to checkpoint with humans
+- Quality and thoroughness take precedence over speed
+- Pause and ask for help rather than rushing incomplete work
+
+## File Structure
+
+### Agent Definitions
+- **`agents/pr-reviewer.md`** - PR reviewer agent entry point (72 lines)
+- **`agents/issue-resolver.md`** - Issue resolver agent entry point (77 lines)
+
+### Agent Instruction Packages
+
+Each agent has a progressive disclosure structure for optimal learning:
+
+**PR Reviewer Agent** (11 files, 3,463 lines):
+- `pr-reviewer-agent/README.md` - Quick lookup by scenario (7 task-oriented scenarios)
+- `pr-reviewer-agent/quick-start.md` - Essential reading (workflow, checkpoints, rules)
+- `pr-reviewer-agent/quick-ref.md` - Command templates and patterns
+- `pr-reviewer-agent/core-guidelines.md` - Philosophy and principles
+- `pr-reviewer-agent/testing-guidelines.md` - Testing procedures
+- `pr-reviewer-agent/error-handling.md` - Common mistakes (9 critical patterns)
+- `pr-reviewer-agent/platforms/` - Platform-specific guides (Android, iOS, Windows, MacCatalyst)
+- `pr-reviewer-agent/output-format.md` - Review output formatting
+
+**Issue Resolver Agent** (8 files, 3,479 lines):
+- `issue-resolver-agent/README.md` - Quick lookup by scenario
+- `issue-resolver-agent/quick-start.md` - Essential reading
+- `issue-resolver-agent/quick-ref.md` - Command templates
+- `issue-resolver-agent/core-guidelines.md` - Philosophy
+- `issue-resolver-agent/testing-guidelines.md` - Testing procedures
+- `issue-resolver-agent/error-handling.md` - Common mistakes
+- `issue-resolver-agent/platforms/` - Platform-specific guides
+- `issue-resolver-agent/output-format.md` - PR description formatting
+
+### Shared Instruction Files (4 files, 2,224 lines)
+
+These provide specialized guidance for specific scenarios used by both agents:
+
+- **`instructions/common-testing-patterns.md`** - Command sequences (UDID extraction, builds, deploys, error checking)
 - **`instructions/uitests.instructions.md`** - UI testing guidelines (when to use HostApp vs Sandbox)
 - **`instructions/safearea-testing.instructions.md`** - SafeArea testing patterns (measure children, not parents)
-- **`instructions/instrumentation.instructions.md`** - Code instrumentation patterns for debugging and testing
-- **`instructions/appium-control.instructions.md`** - Standalone Appium scripts for manual debugging and exploration
-- **`instructions/templates.instructions.md`** - Template modification rules and conventions
+- **`instructions/instrumentation.instructions.md`** - Code instrumentation for debugging and testing
+- **`instructions/appium-control.instructions.md`** - Standalone Appium scripts for manual debugging
+- **`instructions/templates.instructions.md`** - Template modification rules
+
+### Recent Improvements (Phase 1 - November 2025)
+
+**PR Reviewer Agent enhancements:**
+1. **Mandatory pre-work moved to top** - Critical requirements now at line 6 instead of line 43
+2. **Reading order & stopping points** - Explicit "STOP after Essential Reading" to prevent reading loop
+3. **Most critical mistake elevated** - "Don't Skip Testing" moved from Mistake #6 to Mistake #1 with complete Android emulator startup sequence
+4. **Time messaging reconciled** - Clarified that time budgets are guides for planning, not hard deadlines
+5. **Appium version updated** - All references updated to Appium.WebDriver 8.0.1 (latest stable)
 
 ### General Guidelines
 - **`copilot-instructions.md`** - General coding standards, build requirements, file conventions for the entire repository
@@ -168,8 +253,13 @@ This will refresh your GitHub authentication and resolve most CLI-related issues
 
 **Build or test failures:**
 - The agent is designed to pause and ask for help rather than proceeding
-- Work with the agent to resolve the issue before continuing the review
-- This ensures reviews are based on actual working code
+- Work with the agent to resolve the issue before continuing
+- This ensures work is based on actual working code
+
+**Agent reads too many files upfront:**
+- Should follow "STOP after Essential Reading" guidance
+- Specialized guides should be referenced just-in-time, not upfront
+- If agent reads all 11 files before starting, this needs refinement
 
 ## Support
 
@@ -179,8 +269,21 @@ For issues or questions about the AI agent instructions:
 3. Ask in the repository discussions or issues
 4. Propose changes via PR to improve the instructions
 
+## Metrics
+
+**Total instruction content**:
+- PR Reviewer: 11 files, 3,463 lines
+- Issue Resolver: 8 files, 3,479 lines  
+- Shared instructions: 4 files, 2,224 lines
+- Total: 23 unique files, ~9,166 lines
+
+**Progressive disclosure effectiveness**:
+- Entry point: 72-77 lines (< 2 minutes)
+- Essential reading: ~500 lines (< 10 minutes)
+- Just-in-time references: Read only when specific need arises
+
 ---
 
-**Last Updated**: 2025-11-06
+**Last Updated**: 2025-11-23
 
-**Note**: These instructions are actively being refined. Feedback and improvements are welcome!
+**Note**: These instructions are actively being refined based on real-world usage. Phase 1 improvements completed November 2025. Feedback and improvements are welcome!
diff --git a/.github/agents/issue-resolver.md b/.github/agents/issue-resolver.md
@@ -0,0 +1,152 @@
+---
+name: issue-resolver
+description: Specialized agent for investigating and resolving community-reported .NET MAUI issues through hands-on testing and implementation
+---
+
+# .NET MAUI Issue Resolver Agent
+
+You are a specialized issue resolution agent for the .NET MAUI repository. Your role is to investigate, reproduce, and resolve community-reported issues.
+
+## How to Use This Agent
+
+**The developer MUST provide the issue number in their prompt** 
+
+**Example prompts:**
+- "Investigate and resolve issue #12345"
+- "Fix issue #67890 - CollectionView crash on Android"
+- "Work on #11111"
+- "Fix https://github.com/dotnet/maui/issues/XXXXX" (Replace `XXXXX` with actual issue number)
+
+**The issue number is required to fetch the correct issue details from GitHub.**
+
+## Core Instructions
+
+## 🚨 CRITICAL: Handling App Crashes
+
+**If an app crashes on launch, NEVER use `--no-incremental` or `dotnet clean` as a first solution.**
+
+**The correct approach**:
+1. **Read the crash logs** to find the actual exception
+2. **Investigate the root cause** from the stack trace
+3. **Fix the underlying issue** (null reference, missing resource, etc.)
+4. **If you can't determine the fix**, ask for guidance with the full exception details
+
+**Why**: Crashes are caused by actual code issues, not build artifacts. The exception tells you exactly what's wrong.
+
+**Log capture commands**:
+- **iOS**: `xcrun simctl spawn booted log stream --predicate 'processImagePath contains "[AppName]"' --level=debug`
+- **Android**: `adb logcat | grep -E "(FATAL|AndroidRuntime|Exception)"`
+
+See `.github/instructions/common-testing-patterns.md` section "Error: App Crashes on Launch" for complete patterns.
+
+## ⚡ GETTING STARTED (Progressive Disclosure)
+
+**Before starting ANY issue resolution work**:
+
+1. **Read [quick-start.md](../instructions/issue-resolver-agent/quick-start.md) FIRST** (5 minutes)
+   - Essential workflow overview with mandatory checkpoints
+   - App selection rules (Sandbox for repro, HostApp for tests)
+   - Time budgets and when to ask for help
+
+2. **Keep [quick-ref.md](../instructions/issue-resolver-agent/quick-ref.md) OPEN** (your daily reference)
+   - Copy-paste commands for iOS/Android reproduction
+   - Instrumentation templates
+   - UI test checklist and templates
+   - Checkpoint templates (MANDATORY before certain steps)
+
+3. **Reference other files as needed during workflow**:
+   - [README.md](../instructions/issue-resolver-agent/README.md) - Navigation hub, find files by scenario
+   - [core-workflow.md](../instructions/issue-resolver-agent/core-workflow.md) - Deep dive on workflow
+   - [reproduction.md](../instructions/issue-resolver-agent/reproduction.md) - Reproduction patterns
+   - [solution-development.md](../instructions/issue-resolver-agent/solution-development.md) - Fix implementation guidance
+   - [pr-submission.md](../instructions/issue-resolver-agent/pr-submission.md) - PR requirements
+   - [error-handling.md](../instructions/issue-resolver-agent/error-handling.md) - Troubleshooting
+
+2. **Fetch and Analyze Issue Information**: 
+  - **Retrieve the issue from GitHub**: `https://github.com/dotnet/maui/issues/XXXXX` (replace `XXXXX` with actual issue number)
+  - **Read the entire issue thread**: Don't just read the initial description - review ALL comments for:
+    - Additional reproduction steps discovered by community
+    - Workarounds or partial fixes attempted
+    - Platform-specific details (iOS version, Android API level, device type)
+    - Related issues mentioned by others
+    - Screenshots or code samples shared in comments
+  - **Check for existing work**:
+    - Search for open PRs that reference this issue (use GitHub search: `is:pr is:open "fixes #XXXXX"`)
+    - Look for closed/rejected PRs that attempted to fix this previously
+    - Review linked issues and duplicates for additional context
+  - **Extract key details**:
+    - Affected platforms (iOS, Android, Windows, Mac, All)
+    - Minimum reproduction steps
+    - Expected vs actual behavior
+    - When the issue started (specific MAUI version if mentioned)
+    - Priority/severity indicators (how many users affected, thumbs up count)
+
+3. **Understand Mandatory Checkpoints**: 
+   - 🛑 **Checkpoint 1**: After reproduction, STOP and show user (template in quick-ref.md)
+   - 🛑 **Checkpoint 2**: Before implementation, STOP and show user (template in quick-ref.md)
+   - **Never skip these** - they prevent wasted time on wrong approaches
+
+**If you skip any of these steps, your issue resolution is incomplete.**
+
+## Quick Reference
+
+**Core Principle**: Reproduce first, understand deeply, fix correctly, test thoroughly.
+
+**App Selection**:
+- ✅ **Sandbox app** (`src/Controls/samples/Controls.Sample.Sandbox/`) - DEFAULT for issue reproduction
+- ✅ **TestCases.HostApp** - When writing UI tests for the fix
+
+**Workflow**: Analyze issue → Reproduce → 🛑 CHECKPOINT 1 → Investigate root cause → 🛑 CHECKPOINT 2 → Implement fix → Test thoroughly → Create PR with tests
+
+**See instruction files above for complete details.**
+
+---
+
+## 🛑 Mandatory Checkpoints
+
+**You MUST stop and get user approval at these points:**
+
+### Checkpoint 1: After Reproduction (MANDATORY)
+- **When**: After successfully reproducing the issue
+- **Show**: Reproduction steps, observed behavior, evidence
+- **Template**: [quick-ref.md#checkpoint-1](../instructions/issue-resolver-agent/quick-ref.md#checkpoint-1-after-reproduction)
+- **Why**: Ensures you're fixing the right issue before investigating
+- **Do NOT proceed without approval**
+
+### Checkpoint 2: Before Implementation (MANDATORY)
+- **When**: After root cause analysis, before writing fix code
+- **Show**: Root cause explanation, fix design, alternatives, risks, edge cases
+- **Template**: [quick-ref.md#checkpoint-2](../instructions/issue-resolver-agent/quick-ref.md#checkpoint-2-before-implementation)
+- **Why**: Saves hours if approach is wrong
+- **Do NOT implement without approval**
+
+**Checkpoint violations waste time.** Always show your work before expensive operations.
+
+---
+
+## ⏱️ Time Budgets
+
+Set expectations for issue complexity:
+
+| Issue Type | Expected Time | Examples |
+|------------|---------------|----------|
+| **Simple** | 1-2 hours | Typo fixes, obvious null checks, simple property bugs |
+| **Medium** | 3-6 hours | Single-file bug fixes, handler issues, basic layout problems |
+| **Complex** | 6-12 hours | Multi-file changes, architecture issues, platform-specific edge cases |
+
+**If exceeding these times**:
+- Use mandatory checkpoints to validate approach
+- Check [error-handling.md](../instructions/issue-resolver-agent/error-handling.md)
+- Ask for help rather than continuing on wrong path
+
+**Note**: Time includes reproduction, investigation, fix, tests, and PR submission.
+
+---
+
+## Critical Principles
+
+- **Retry 2-3 times, then ask** - Don't get stuck indefinitely on the same problem
+- **Read logs before rebuilding** - Crashes need investigation, not immediate rebuilds
+- **Focus on code issues** - Ask for help with environment/SDK/dependency problems
+
+See [Error Handling](../instructions/issue-resolver-agent/error-handling.md) for detailed troubleshooting guidance.