dotnet · PureWeen · Jan 20, 2026 · Jan 16, 2026 · Jan 16, 2026 · Jan 16, 2026
diff --git a/.github/agents/learn-from-pr.md b/.github/agents/learn-from-pr.md
@@ -0,0 +1,113 @@
+---
+name: learn-from-pr
+description: Analyzes completed PRs for lessons learned, then applies improvements to instruction files, skills, and documentation.
+---
+
+# Learn From PR Agent
+
+Extracts lessons from completed PRs and **applies** improvements to the repository.
+
+## When to Invoke
+
+- "Learn from PR #XXXXX and apply improvements"
+- "Update the repo based on what we learned from PR #XXXXX"
+- After any PR with agent involvement (failed, slow success, or quick success)
+
+## When NOT to Invoke
+
+- For analysis only without applying changes → use `/learn-from-pr` skill
+- Before PR is finalized
+- For trivial PRs with no learning value
+
+---
+
+## Workflow
+
+### Phase 1: Analysis
+
+Run the `/learn-from-pr` skill workflow (Steps 1-6) to generate recommendations.
+
+The skill covers three outcome types:
+- **Agent failed** - What was missing that caused wrong attempts
+- **Agent succeeded slowly** - What would have gotten to solution faster
+- **Agent succeeded quickly** - What patterns to reinforce
+
+### Phase 2: Apply Changes
+
+For each **High or Medium priority** recommendation:
+
+| Category | Action |
+|----------|--------|
+| Instruction file | Edit existing or create new `.github/instructions/*.instructions.md` |
+| Skill enhancement | Edit `.github/skills/*/SKILL.md` |
+| Architecture doc | Edit `/docs/design/*.md` (detailed) or create quick-reference in `.github/architecture/` |
+| General AI guidance | Edit `.github/copilot-instructions.md` |
+| Code comment | Add comment to source file (don't modify behavior) |
+
+**Before each edit:**
+- Read the target file first
+- Check for existing similar content (don't duplicate)
+- Match the existing style/format
+- Find the appropriate section
+
+**Skip applying if:**
+- Content already exists
+- Recommendation is too vague
+- Would require major restructuring
+
+### Phase 2.5: Verify Changes
+
+After applying changes:
+
+1. Run `git diff` to review all edits
+2. Verify no syntax errors in modified files (valid markdown)
+3. Confirm style matches existing content
+4. If issues found, fix or revert before reporting
+
+### Phase 3: Report
+
+Present a summary:
+
+```markdown
+## Changes Applied
+
+| File | Change |
+|------|--------|
+| [path] | [what was added/modified] |
+
+## Not Applied
+
+| Recommendation | Reason |
+|----------------|--------|
+| [rec] | [why skipped] |
+```
+
+---
+
+## Error Handling
+
+| Situation | Action |
+|-----------|--------|
+| PR not found | Ask user to verify PR number |
+| No session markdown | Proceed with PR diff analysis only |
+| Target file doesn't exist | Create if instruction/architecture doc, skip if code |
+| Duplicate content exists | Skip, note in report |
+| Unclear where to add | Ask user for guidance |
+
+## Constraints
+
+- **Only apply High/Medium priority** - Report Low priority without applying
+- **Don't duplicate** - Check existing content first
+- **Match style** - Read file before editing
+- **Code comments only** - Never modify code behavior
+- **No linter implementation** - File issue instead of building analyzers
+
+---
+
+## Difference from Skill
+
+| Aspect | `/learn-from-pr` Skill | This Agent |
+|--------|------------------------|------------|
+| Output | Recommendations to discuss | Applied changes |
+| Mode | Analysis only | Autonomous |
+| Use when | Want to review without applying | CI automation |
diff --git a/.github/agents/pr.md b/.github/agents/pr.md
@@ -39,6 +39,23 @@ After Gate passes, read `.github/agents/pr/post-gate.md` for **Phases 4-5**.
 └─────────────────────────────────────────┘     └─────────────────────────────────────────────┘
 ```
 
+---
+
+## Phase Completion Protocol (CRITICAL)
+
+**Before changing ANY phase status to ✅ COMPLETE:**
+
+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
+
+**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:
@@ -326,6 +343,14 @@ The test result will be updated to `✅ PASS (Gate)` after Gate passes.
 3. Add edge cases and any disagreements (if PR exists)
 4. Change 🧪 Tests status to `▶️ IN PROGRESS`
 
+**Before marking ✅ COMPLETE, verify state file contains:**
+- [ ] Issue summary filled (not [PENDING])
+- [ ] Platform checkboxes marked
+- [ ] Files Changed table populated (if PR exists)
+- [ ] PR Discussion Summary documented (if PR exists)
+- [ ] All [PENDING] placeholders replaced
+- [ ] State file committed
+
 ---
 
 ## 🧪 TESTS: Create/Verify Reproduction Tests (Phase 2)
@@ -385,6 +410,12 @@ The script auto-detects mode based on git diff. If only test files changed, it v
 4. Change 🧪 Tests status to `✅ COMPLETE`
 5. Change 🚦 Gate status to `▶️ IN PROGRESS`
 
+**Before marking ✅ COMPLETE, verify state file contains:**
+- [ ] Test file paths documented
+- [ ] "Tests verified to FAIL" note added
+- [ ] Test category identified
+- [ ] State file committed
+
 ---
 
 ## 🚦 GATE: Verify Tests Catch the Issue (Phase 3)
@@ -432,6 +463,12 @@ pwsh .github/skills/verify-tests-fail-without-fix/scripts/verify-tests-fail.ps1
 2. Change 🚦 Gate status to `✅ PASSED`
 3. Proceed to Phase 4
 
+**Before marking ✅ PASSED, verify state file contains:**
+- [ ] Result shows PASSED ✅ or FAILED ❌
+- [ ] Test behavior documented
+- [ ] Platform tested noted
+- [ ] State file committed
+
 ---
 
 ## ⛔ STOP HERE

diff --git a/.github/agents/pr/post-gate.md b/.github/agents/pr/post-gate.md
@@ -15,6 +15,21 @@ If Gate is not passed, go back to `.github/agents/pr.md` and complete phases 1-3
 
 ---
 
+## Phase Completion Protocol (CRITICAL)
+
+**Before changing ANY phase status to ✅ COMPLETE:**
+
+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
+
+**Rule:** Status ✅ means "documentation complete", not "I finished thinking about it"
+
+---
+
 ## 🔧 FIX: Explore and Select Fix (Phase 4)
 
 > **SCOPE**: Explore independent fix alternatives using `try-fix` skill, compare with PR's fix, select the best approach.
@@ -37,25 +52,37 @@ The purpose of Phase 4 is NOT to re-test the PR's fix, but to:
 
 Invoke the `try-fix` skill repeatedly. The skill handles one fix attempt per invocation.
 
+**IMPORTANT:** Always pass the `state_file` parameter so try-fix can record its results:
+```
+state_file: .github/agent-pr-session/pr-XXXXX.md
+```
+
+try-fix will automatically append rows to the Fix Candidates table and set the "Exhausted" field. You remain responsible for:
+- Setting "Selected Fix" field with reasoning
+- Updating phase status to ✅ COMPLETE
+
 ```
 ┌─────────────────────────────────────────────────────────────┐
 │  Agent orchestration loop                                   │
 ├─────────────────────────────────────────────────────────────┤
 │                                                             │
 │  attempts = 0                                               │
 │  max_attempts = 5                                           │
+│  state_file = ".github/agent-pr-session/pr-XXXXX.md"        │
 │                                                             │
 │  while (attempts < max_attempts):                           │
-│      result = invoke try-fix skill                          │
+│      result = invoke try-fix skill (with state_file)        │
 │      attempts++                                             │
 │                                                             │
 │      if result.exhausted:                                   │
 │          break  # try-fix has no more ideas                 │
 │                                                             │
 │      # result.passed indicates if this attempt worked       │
+│      # try-fix already recorded to state file               │
 │      # Continue loop to explore more alternatives           │
 │                                                             │
 │  # After loop: compare all try-fix results vs PR's fix      │
+│  # Update "Exhausted" and "Selected Fix" fields             │
 │                                                             │
 └─────────────────────────────────────────────────────────────┘
 ```
@@ -73,8 +100,9 @@ Each `try-fix` invocation:
 3. Proposes ONE new independent fix idea
 4. Implements and tests it
 5. Records result (with failure analysis if it failed)
-6. Reverts all changes (restores PR's fix)
-7. Returns `{passed: bool, exhausted: bool}`
+6. **Updates state file** (appends row to Fix Candidates table if state_file provided)
+7. Reverts all changes (restores PR's fix)
+8. Returns `{passed: bool, exhausted: bool}`
 
 See `.github/skills/try-fix/SKILL.md` for full details.
 
@@ -134,6 +162,15 @@ Update the state file:
 4. Change 🔧 Fix status to `✅ COMPLETE`
 5. Change 📋 Report status to `▶️ IN PROGRESS`
 
+**Before marking ✅ COMPLETE, verify state file contains:**
+- [ ] Root Cause Analysis filled in (if applicable)
+- [ ] Fix Candidates table has numbered rows for each try-fix attempt
+- [ ] Each row has: approach, test result, files changed, notes
+- [ ] "Exhausted" field set (Yes/No)
+- [ ] "Selected Fix" populated with reasoning
+- [ ] No ⏳ PENDING markers remain in Fix section
+- [ ] State file committed
+
 ---
 
 ## 📋 REPORT: Final Report (Phase 5)
@@ -233,6 +270,13 @@ Update all phase statuses to complete.
 2. Update all phases to `✅ COMPLETE` or `✅ PASSED`
 3. Present final result to user
 
+**Before marking ✅ COMPLETE, verify state file contains:**
+- [ ] Final recommendation (APPROVE/REQUEST_CHANGES/COMMENT)
+- [ ] Summary of findings
+- [ ] Key technical insights documented
+- [ ] Overall status changed to final recommendation
+- [ ] State file committed
+
 ---
 
 ## Common Mistakes in Post-Gate Phases

diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md
@@ -6,6 +6,10 @@ description: "Guidance for GitHub Copilot when working on the .NET MAUI reposito
 
 This document provides specific guidance for GitHub Copilot when working on the .NET MAUI repository. It serves as context for understanding the project structure, development workflow, and best practices.
 
+## Code Review Instructions
+
+When performing a code review on PRs that change functional code, run the pr-finalize skill to verify that the PR title and description accurately match the actual implementation. This ensures proper documentation and helps maintain high-quality commit messages.
+
 ## Repository Overview
 
 **.NET MAUI** is a cross-platform framework for creating mobile and desktop applications with C# and XAML. This repository contains the core framework code that enables development for Android, iOS, iPadOS, macOS, and Windows from a single shared codebase.
@@ -177,9 +181,18 @@ Always put that at the top, without the block quotes. Without it, users will NOT
 
 
 
-## Custom Agents
+## Custom Agents and Skills
+
+The repository includes specialized custom agents and reusable skills for specific tasks.
+
+### Skills vs Agents
 
-The repository includes specialized custom agents for specific tasks. These agents are available to GitHub Copilot and can be invoked for their respective specializations:
+| Aspect | Skills | Agents |
+|--------|--------|--------|
+| **Invoke** | `/skill-name` or direct request | Delegate to agent |
+| **Output** | Analysis, recommendations | Actions, changes applied |
+| **Interaction** | Interactive discussion | Autonomous workflow |
+| **Example** | `/learn-from-pr` → recommendations | learn-from-pr agent → applies changes |
 
 ### Available Custom Agents
 
@@ -200,15 +213,65 @@ The repository includes specialized custom agents for specific tasks. These agen
    - **Trigger phrases**: "test this PR", "validate PR #XXXXX in Sandbox", "reproduce issue #XXXXX", "try out in Sandbox"
    - **Do NOT use for**: Code review (use pr agent), writing automated tests (use uitest-coding-agent)
 
+4. **learn-from-pr** - Extracts lessons from PRs and applies improvements to the repository
+   - **Use when**: After complex PR, want to improve instruction files/skills based on lessons learned
+   - **Capabilities**: Analyzes PR, identifies failure modes, applies improvements to instruction files, skills, code comments
+   - **Trigger phrases**: "learn from PR #XXXXX and apply improvements", "improve repo based on what we learned", "update skills based on PR"
+   - **Output**: Applied changes to instruction files, skills, architecture docs, code comments
+   - **Do NOT use for**: Analysis only without applying changes → Use `/learn-from-pr` skill instead
+
 ### Reusable Skills
 
 Skills are modular capabilities that can be invoked directly or used by agents. Located in `.github/skills/`:
 
+#### User-Facing Skills
+
 1. **issue-triage** (`.github/skills/issue-triage/SKILL.md`)
    - **Purpose**: Query and triage open issues that need milestones, labels, or investigation
-   - **Trigger phrases**: "find issues to triage", "show me old Android issues", "what issues need attention", "triage Android issues"
+   - **Trigger phrases**: "find issues to triage", "show me old Android issues", "what issues need attention"
    - **Scripts**: `init-triage-session.ps1`, `query-issues.ps1`, `record-triage.ps1`
-   - **Used by**: Any agent or direct invocation
+
+2. **find-reviewable-pr** (`.github/skills/find-reviewable-pr/SKILL.md`)
+   - **Purpose**: Finds open PRs in dotnet/maui and dotnet/docs-maui that need review
+   - **Trigger phrases**: "find PRs to review", "show milestoned PRs", "find partner PRs"
+   - **Scripts**: `query-reviewable-prs.ps1`
+   - **Categories**: P/0, milestoned, partner, community, recent, docs-maui
+
+3. **pr-finalize** (`.github/skills/pr-finalize/SKILL.md`)
+   - **Purpose**: Verifies PR title and description match actual implementation. Works on any PR. Optionally updates agent session markdown if present.
+   - **Trigger phrases**: "finalize PR #XXXXX", "check PR description for #XXXXX", "review commit message"
+   - **Used by**: Before merging any PR, when description may be stale
+   - **Note**: Does NOT require agent involvement or session markdown - works on any PR
+
+4. **learn-from-pr** (`.github/skills/learn-from-pr/SKILL.md`)
+   - **Purpose**: Analyzes completed PR to identify repository improvements (analysis only, no changes applied)
+   - **Trigger phrases**: "what can we learn from PR #XXXXX?", "how can we improve agents based on PR #XXXXX?"
+   - **Used by**: After complex PRs, when agent struggled to find solution
+   - **Output**: Prioritized recommendations for instruction files, skills, code comments
+   - **Note**: For applying changes automatically, use the learn-from-pr agent instead
+
+5. **write-tests** (`.github/skills/write-tests/SKILL.md`)
+   - **Purpose**: Creates UI tests for GitHub issues and verifies they reproduce the bug
+   - **Trigger phrases**: "write tests for #XXXXX", "create test for issue", "add UI test coverage"
+   - **Output**: Test files that fail without fix, pass with fix
+
+6. **verify-tests-fail-without-fix** (`.github/skills/verify-tests-fail-without-fix/SKILL.md`)
+   - **Purpose**: Verifies UI tests catch the bug before fix and pass with fix
+   - **Two modes**: Verify failure only (test creation) or full verification (test + fix)
+   - **Used by**: After creating tests, before considering PR complete
+
+7. **pr-build-status** (`.github/skills/pr-build-status/SKILL.md`)
+   - **Purpose**: Retrieves Azure DevOps build information for PRs (build IDs, stage status, failed jobs)
+   - **Trigger phrases**: "check build for PR #XXXXX", "why did PR build fail", "get build status"
+   - **Used by**: When investigating CI failures
+
+#### Internal Skills (Used by Agents)
+
+8. **try-fix** (`.github/skills/try-fix/SKILL.md`)
+   - **Purpose**: Proposes ONE independent fix approach, applies it, tests, records result with failure analysis, then reverts
+   - **Used by**: pr agent Phase 3 (Fix phase) - rarely invoked directly by users
+   - **Behavior**: Reads prior attempts to learn from failures. Max 5 attempts per session.
+   - **Output**: Updates session markdown with attempt results and failure analysis
 
 ### Using Custom Agents